state

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: 12 Imported by: 0

Documentation

Overview

Package state contains the process-owned state coordination used by compaction preservation. It deliberately does not interpret capsule facts or execute background work; it only binds bounded state to the authoritative parent branch and serializes lifecycle updates.

Package state contains the feature-owned state coordination used by compaction continuity preservation. It binds bounded state to the authoritative parent branch and serializes lifecycle updates.

Index

Constants

View Source 
const (
	DefaultMaxEntries        = 1024
	DefaultMaxPreviewIntents = 1024
	DefaultTTL               = 2 * time.Hour
	DefaultMaxCapsuleBytes   = 1 << 20
	DefaultMaxSourceBytes    = 4 << 20
)

Variables

View Source 
var (
	ErrInvalidBranchKey         = errors.New("compactioncontinuity: invalid branch key")
	ErrBranchNotFound           = errors.New("compactioncontinuity: branch not found")
	ErrBranchMismatch           = errors.New("compactioncontinuity: branch binding mismatch")
	ErrRevisionConflict         = errors.New("compactioncontinuity: revision conflict")
	ErrPendingJobMismatch       = errors.New("compactioncontinuity: pending job mismatch")
	ErrPreviewIntentMismatch    = errors.New("compactioncontinuity: preview intent mismatch")
	ErrInvalidTransaction       = errors.New("compactioncontinuity: invalid transaction")
	ErrBranchLimit              = errors.New("compactioncontinuity: branch limit reached")
	ErrPreviewIntentLimit       = errors.New("compactioncontinuity: preview intent limit reached")
	ErrInjectionMismatch        = errors.New("compactioncontinuity: pending injection mismatch")
	ErrInjectionAlreadyReleased = errors.New("compactioncontinuity: injection already released")
	ErrInvalidState             = errors.New("compactioncontinuity: invalid persisted state")
	ErrStateTooLarge            = errors.New("compactioncontinuity: state blob exceeds bound")
)

Functions

func BranchBinding 

func BranchBinding(k BranchKey) (string, error)

BranchBinding derives the stable content-free binding for a key.

Types

type BranchCoordinator 

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

func NewBranchCoordinator 

func NewBranchCoordinator(ctx context.Context, cfg Config) (*BranchCoordinator, error)

NewBranchCoordinator constructs the process-owned coordinator.

func (*BranchCoordinator) BindPreviewIntent 

func (c *BranchCoordinator) BindPreviewIntent(ctx context.Context, key BranchKey, intentKey, transactionID string) (BranchState, error)

BindPreviewIntent consumes a non-billable intent after a successful primary Open and records its committed transaction identity.

func (*BranchCoordinator) Capture 

func (c *BranchCoordinator) Capture(ctx context.Context, key BranchKey) (string, error)

Capture records the parent branch before detached child creation. It is idempotent for an existing non-expired branch.

func (*BranchCoordinator) CommitCapsule 

func (c *BranchCoordinator) CommitCapsule(ctx context.Context, key BranchKey, expectedRevision uint64, capsule []byte, digest [32]byte, sourceHighWatermark string) (BranchState, error)

CommitCapsule commits an opaque capsule revision using compare-and-swap semantics. expectedRevision zero is valid only for an empty branch.

func (*BranchCoordinator) CommitCapsuleForJob 

func (c *BranchCoordinator) CommitCapsuleForJob(ctx context.Context, key BranchKey, jobID auxiliary.JobID, branchBinding string, expectedRevision uint64, capsule []byte, digest [32]byte, sourceHighWatermark string) (BranchState, error)

CommitCapsuleForJob applies a revision only if the pending job and parent binding still match, preventing late child results from moving branches.

func (*BranchCoordinator) CommitReleasedInjection 

func (c *BranchCoordinator) CommitReleasedInjection(ctx context.Context, key BranchKey, watermark InjectionWatermark) (BranchState, error)

CommitReleasedInjection advances the durable compound watermark only after successful final client release. A pre-release validation/Open/abort path must leave PendingInjection untouched.

func (*BranchCoordinator) CommitSource 

func (c *BranchCoordinator) CommitSource(ctx context.Context, key BranchKey, expectedRevision uint64, source []byte, highWatermark string) (BranchState, error)

CommitSource stores a bounded sanitized source snapshot on the post-open refresh path (RequestOpened, after the preview intent is bound). It does not advance the capsule revision, but still compare-checks the current revision. Pre-open preparation persists only the preview intent and the deterministic capsule with the prior watermark; that staged state stays TTL-bounded and inert until a successful open binds the preview intent; failed opens must never bind intents, submit billable jobs, or commit release watermarks (§571).

func (*BranchCoordinator) MergeCapsule 

func (c *BranchCoordinator) MergeCapsule(ctx context.Context, key BranchKey, jobID auxiliary.JobID, branchBinding string, baseRevision uint64, capsule []byte, digest [32]byte) (BranchState, error)

MergeCapsule validates pending job ownership and commits a late result as a new revision. Raw result ownership is outside this coordinator.

func (*BranchCoordinator) RecordPendingJob 

func (c *BranchCoordinator) RecordPendingJob(ctx context.Context, key BranchKey, jobID auxiliary.JobID, targetRevision uint64) (BranchState, error)

RecordPendingJob binds a committed background job to the captured parent.

func (*BranchCoordinator) RecordPreviewIntent 

func (c *BranchCoordinator) RecordPreviewIntent(ctx context.Context, key BranchKey, intent PreviewIntent) (BranchState, error)

func (*BranchCoordinator) Retire 

func (c *BranchCoordinator) Retire(ctx context.Context, key BranchKey) error

Retire removes a branch and its pending state, used for explicit reset/new A-leg replacement. It does not cancel external background work.

func (*BranchCoordinator) SetPendingInjection 

func (c *BranchCoordinator) SetPendingInjection(ctx context.Context, key BranchKey, target InjectionTarget) (BranchState, error)

func (*BranchCoordinator) Snapshot 

func (c *BranchCoordinator) Snapshot(_ context.Context, key BranchKey) (BranchState, bool, error)

Snapshot returns a defensive copy of state for the captured parent branch.

func (*BranchCoordinator) ValidateInjection 

func (c *BranchCoordinator) ValidateInjection(_ context.Context, key BranchKey, target InjectionTarget) (BranchState, error)

ValidateInjection enforces branch and pending-target consistency before a caller mutates a canonical request.

func (*BranchCoordinator) ValidatePendingJob 

func (c *BranchCoordinator) ValidatePendingJob(_ context.Context, key BranchKey, jobID auxiliary.JobID) (BranchState, error)

ValidatePendingJob is the common guard for Await, merge, revision, and reinjection paths. It never accepts a child A-leg as a lookup key.

func (*BranchCoordinator) ValidatePendingJobBinding 

func (c *BranchCoordinator) ValidatePendingJobBinding(ctx context.Context, key BranchKey, jobID auxiliary.JobID, branchBinding string) (BranchState, error)

ValidatePendingJobBinding adds the opaque branch-binding check used around scheduler Await. No external call is made while coordinator state is held.

type BranchKey 

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

BranchKey identifies the authoritative parent primary branch. A private auxiliary child A-leg is never a valid replacement for ALegID.

func CaptureParentBranchKey 

func CaptureParentBranchKey(sessionID, aLegID, principalPartition string) (BranchKey, error)

CaptureParentBranchKey is an explicit name for the pre-child capture point.

func NewBranchKey 

func NewBranchKey(sessionID, aLegID, principalPartition string) (BranchKey, error)

NewBranchKey validates and normalises an authoritative parent key. When no secure session exists, principalPartition must isolate the primary A-leg.

func (BranchKey) Binding 

func (k BranchKey) Binding() string

Binding derives a content-free stable branch identity. Raw session, principal, and A-leg identifiers need not cross the extractor boundary.

func (BranchKey) Validate 

func (k BranchKey) Validate() error

Validate checks that this key has an authoritative primary A-leg and either a secure session or a principal-isolated fallback partition.

type BranchState 

type BranchState struct {
	Revision                  uint64              `json:"revision"`
	CapsuleJSON               json.RawMessage     `json:"capsule_json,omitempty"`
	CapsuleDigest             [32]byte            `json:"capsule_digest,omitempty"`
	SourceHighWatermark       string              `json:"source_high_watermark,omitempty"`
	SanitizedSourceJSON       json.RawMessage     `json:"sanitized_source_json,omitempty"`
	PendingPreviewIntent      *PreviewIntent      `json:"pending_preview_intent,omitempty"`
	PendingJobID              auxiliary.JobID     `json:"pending_job_id,omitempty"`
	PendingJobTargetRevision  uint64              `json:"pending_job_target_revision,omitempty"`
	PendingJobBranchBinding   string              `json:"pending_job_branch_binding,omitempty"`
	PendingInjection          *InjectionTarget    `json:"pending_injection,omitempty"`
	LastReleasedInjection     *InjectionWatermark `json:"last_released_injection,omitempty"`
	LastCompactionTransaction string              `json:"last_compaction_transaction,omitempty"`
	UpdatedAt                 time.Time           `json:"updated_at"`
}

BranchState is the bounded opaque coordinator state. Capsule/source bytes are intentionally not interpreted here.

type Config 

type Config struct {
	Store             lipstate.Store
	MaxEntries        int
	MaxPreviewIntents int
	TTL               time.Duration
	Now               func() time.Time
	MaxCapsuleBytes   int
	MaxSourceBytes    int
}

Config bounds process state and optionally supplies the process ExtensionState as opaque backing. Store is never used as semantic authority.

type InjectionTarget 

type InjectionTarget struct {
	BoundaryKey     string `json:"boundary_key"`
	CapsuleRevision uint64 `json:"capsule_revision"`
}

type InjectionWatermark 

type InjectionWatermark struct {
	BranchBinding   string `json:"branch_binding"`
	BoundaryKey     string `json:"boundary_key"`
	CapsuleRevision uint64 `json:"capsule_revision"`
}

type PreviewIntent 

type PreviewIntent struct {
	Key                  string `json:"key"`
	TargetSourceRevision uint64 `json:"target_source_revision"`
}

PreviewIntent is a non-billable completion-only boundary. It becomes a committed transaction only after the corresponding primary Open succeeds.

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.