sessionpark

package
v0.133.2 Latest Latest
Warning

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

 Go to latest Published: Sep 16, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package sessionpark stores a complete, durable checkpoint for a parked WB session. It deliberately contains no Git mutation or transport logic.

Index

Constants

View Source 
const (
	EnvelopeSchemaVersion    = 1
	RequestSchemaVersion     = 1
	ReceiptSchemaVersion     = 1
	EnvelopeKind             = "session_park_resume"
	MaxEnvelopeBytes         = 1 << 20
	MaxMembers               = 32
	MaxFieldBytes            = 4096
	TargetDirName            = "park-resumes"
	EnvelopeFileName         = "envelope.json"
	ContinuationFileName     = "continuation.md"
	SuccessorContextFileName = "successor-context.md"
	MaxSuccessorContextBytes = 256 << 10
)
View Source 
const (
	SchemaVersion        = 1
	MaxContinuationBytes = 64 << 10
	MaxBundleBytes       = 4 << 20

	SourceDirName       = "parked-sessions"
	BundleFileName      = "bundle.json"
	LocalNeutralDirName = "local-resume-root"
)
View Source 
const (
	ResumeRouteLocal  = "local"
	ResumeRouteRemote = "remote"
)

Variables

This section is empty.

Functions

func EncodeBundle 

func EncodeBundle(bundle Bundle) ([]byte, error)

func EncodeEnvelope 

func EncodeEnvelope(envelope Envelope) ([]byte, error)

func EncodeReceipt 

func EncodeReceipt(receipt Receipt) ([]byte, error)

func EqualBundle 

func EqualBundle(a, b Bundle) bool

func LaunchAuthority 

func LaunchAuthority(request RemoteRequest, digest sessionmove.Digest, continuationPath string, continuation []byte) (sessionauthority.Launch, error)

func LocalLaunchAuthority 

func LocalLaunchAuthority(bundle Bundle, digest sessionmove.Digest, continuationPath string, continuation []byte) (sessionauthority.Launch, error)

func MemberPin 

func MemberPin(resumeID, memberID string) string

func NewID 

func NewID() (string, error)

func ReceiptSession 

func ReceiptSession(receipt Receipt) session.Record

func RequestedRuntimeModel 

func RequestedRuntimeModel(request RemoteRequest) (string, string)

func TargetWorkLogClaimID 

func TargetWorkLogClaimID(digest sessionmove.Digest, successorID, memberID, repository, sourceClaimID string) (string, error)

TargetWorkLogClaimID binds one member's target claim to the exact parked envelope, successor, repository, and source claim. It is shared with the Work Log corroborator so the prepared claim is independently reproducible.

func TargetWorkLogReference 

func TargetWorkLogReference(request RemoteRequest, digest sessionmove.Digest, member RemoteMember) (string, error)

func ValidateReceipt 

func ValidateReceipt(receipt Receipt, request RemoteRequest, digest sessionmove.Digest) error

Types

type Bundle 

type Bundle struct {
	SchemaVersion   int            `json:"schema_version"`
	ParkedSessionID string         `json:"parked_session_id"`
	Source          session.Record `json:"source"`
	Continuation    string         `json:"continuation"`
	Worktrees       []Worktree     `json:"worktrees"`
	ParkedAt        time.Time      `json:"parked_at"`
}

func DecodeBundle 

func DecodeBundle(raw []byte) (Bundle, error)

type Envelope 

type Envelope struct {
	SchemaVersion int           `json:"schema_version"`
	Kind          string        `json:"kind"`
	Request       RemoteRequest `json:"request"`
}

func DecodeEnvelope 

func DecodeEnvelope(raw []byte) (Envelope, error)

type Event 

type Event struct {
	SchemaVersion  int                `json:"schema_version"`
	Sequence       uint64             `json:"sequence"`
	Type           string             `json:"type"`
	At             time.Time          `json:"at"`
	Successor      *session.Record    `json:"successor,omitempty"`
	RemoteResumeID string             `json:"remote_resume_id,omitempty"`
	RequestDigest  sessionmove.Digest `json:"request_digest,omitempty"`
	TargetMachine  string             `json:"target_machine,omitempty"`
}

type Receipt 

type Receipt struct {
	SchemaVersion          int                `json:"schema_version"`
	ResumeID               string             `json:"resume_id"`
	RequestDigest          sessionmove.Digest `json:"request_digest"`
	ParkedSessionID        string             `json:"parked_session_id"`
	SuccessorWBSessionID   string             `json:"successor_wb_session_id"`
	PredecessorWBSessionID string             `json:"predecessor_wb_session_id"`
	TargetMachine          string             `json:"target_machine"`
	TmuxName               string             `json:"tmux_name"`
	Runtime                string             `json:"runtime"`
	Model                  string             `json:"model,omitempty"`
	NativeHarnessID        string             `json:"native_harness_id,omitempty"`
	AttemptID              string             `json:"attempt_id"`
	AttemptIndex           uint64             `json:"attempt_index"`
	PID                    int                `json:"pid"`
	StartedAt              time.Time          `json:"started_at"`
	Members                []ReceiptMember    `json:"members"`
}

func DecodeReceipt 

func DecodeReceipt(raw []byte) (Receipt, error)

type ReceiptMember 

type ReceiptMember struct {
	MemberID               string `json:"member_id"`
	Repository             string `json:"repository"`
	TargetPath             string `json:"target_path"`
	Pin                    string `json:"pin"`
	Commit                 string `json:"commit"`
	TargetWorkLogReference string `json:"target_work_log_reference"`
}

type RemoteAdmission 

type RemoteAdmission struct {
	Envelope Envelope
	Raw      []byte
	Digest   sessionmove.Digest
	Route    ResumeRoute
	Replay   bool
}

type RemoteMember 

type RemoteMember struct {
	MemberID               string `json:"member_id"`
	Repository             string `json:"repository"`
	RepositoryRemote       string `json:"repository_remote"`
	Branch                 string `json:"branch"`
	Commit                 string `json:"commit"`
	SourceWorkLogReference string `json:"source_work_log_reference"`
}

type RemoteRequest 

type RemoteRequest struct {
	SchemaVersion          int            `json:"schema_version"`
	ResumeID               string         `json:"resume_id"`
	ParkedSessionID        string         `json:"parked_session_id"`
	SuccessorWBSessionID   string         `json:"successor_wb_session_id"`
	PredecessorWBSessionID string         `json:"predecessor_wb_session_id"`
	SourceMachine          string         `json:"source_machine"`
	TargetMachine          string         `json:"target_machine"`
	SourceRuntime          string         `json:"source_runtime"`
	SourceModel            string         `json:"source_model,omitempty"`
	RequestedHarness       string         `json:"requested_harness,omitempty"`
	Continuation           string         `json:"continuation"`
	Members                []RemoteMember `json:"members"`
	CreatedAt              time.Time      `json:"created_at"`
}

RemoteRequest is independent of sessionmove.Request schema v1. It carries one parked aggregate and every exact member needed for an atomic target reconstruction.

func BuildRemoteRequest 

func BuildRemoteRequest(bundle Bundle, target, requestedHarness string, now time.Time) RemoteRequest

type ResumeRoute 

type ResumeRoute struct {
	SchemaVersion   int       `json:"schema_version"`
	ParkedSessionID string    `json:"parked_session_id"`
	Mode            string    `json:"mode"`
	TargetMachine   string    `json:"target_machine,omitempty"`
	Courier         string    `json:"courier,omitempty"`
	SSHHost         string    `json:"ssh_host,omitempty"`
	SSHUser         string    `json:"ssh_user,omitempty"`
	ClaimedAt       time.Time `json:"claimed_at"`
}

func (ResumeRoute) SSHConfig 

func (route ResumeRoute) SSHConfig() (sessionmove.SSHConfig, error)

type SourceLock 

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

func (*SourceLock) Bundle 

func (lock *SourceLock) Bundle() Bundle

func (*SourceLock) Close 

func (lock *SourceLock) Close() error

func (*SourceLock) HeldForSession 

func (lock *SourceLock) HeldForSession(storeRoot, parkID, digest string) bool

func (*SourceLock) RetainSessionDir 

func (lock *SourceLock) RetainSessionDir(storeRoot, parkID, digest string) (*os.File, error)

type State 

type State struct {
	Bundle        Bundle          `json:"bundle"`
	Events        []Event         `json:"events"`
	Status        Status          `json:"status"`
	Successor     *session.Record `json:"successor,omitempty"`
	RemoteReceipt *Receipt        `json:"remote_receipt,omitempty"`
	ResumeRoute   *ResumeRoute    `json:"resume_route,omitempty"`
}

type Status 

type Status string
const (
	StatusParked  Status = "parked"
	StatusResumed Status = "resumed"
)

type Store 

type Store struct{ Root string }

func NewStore 

func NewStore(root string) Store

func (Store) Acquire 

func (s Store) Acquire(ctx context.Context, id string) (*SourceLock, error)

func (Store) ContinuationPathUnderLock 

func (s Store) ContinuationPathUnderLock(lock *SourceLock) (string, error)

ContinuationPathUnderLock returns the deterministic private local-resume artifact only after re-reading it through the retained aggregate descriptor. Callers must pass it through WB_SESSION_CONTINUATION_FILE, never stdout or harness argv.

func (Store) Create 

func (s Store) Create(bundle Bundle) (Bundle, error)

func (Store) EnsureLocalSuccessorContextUnderLock 

func (s Store) EnsureLocalSuccessorContextUnderLock(lock *SourceLock) (string, []byte, error)

EnsureLocalSuccessorContextUnderLock publishes the single private file read by a local successor. It binds the original continuation to every retained member path without copying or modifying worktree bytes.

func (Store) ExistingLocalLaunchRootUnderLock 

func (s Store) ExistingLocalLaunchRootUnderLock(lock *SourceLock) (string, bool, error)

func (Store) FinalizeRemoteUnderLock 

func (s Store) FinalizeRemoteUnderLock(lock *SourceLock, admission RemoteAdmission, now time.Time) (State, error)

func (Store) FindBySource 

func (s Store) FindBySource(wbSessionID string) (Bundle, bool, error)

FindBySource returns the existing aggregate for a source declaration. It is used to repair a crash between aggregate publication and lifecycle marking, so retry never allocates a second parked identity.

func (Store) Load 

func (s Store) Load(id string) (State, error)

func (Store) LoadLocalSuccessorContextUnderLock 

func (s Store) LoadLocalSuccessorContextUnderLock(lock *SourceLock) (string, []byte, bool, error)

func (Store) LoadRemoteReceiptUnderLock 

func (s Store) LoadRemoteReceiptUnderLock(lock *SourceLock, admission RemoteAdmission) (*Receipt, error)

func (Store) LoadUnderLock 

func (s Store) LoadUnderLock(lock *SourceLock) (State, error)

func (Store) LocalLaunchRootUnderLock 

func (s Store) LocalLaunchRootUnderLock(lock *SourceLock) (string, error)

LocalLaunchRootUnderLock returns the first exact retained member, or creates the deterministic aggregate-bound 0700 neutral root for a zero-member park.

func (Store) PrepareLocalUnderLock 

func (s Store) PrepareLocalUnderLock(lock *SourceLock, now time.Time) (ResumeRoute, bool, error)

PrepareLocalUnderLock durably selects the only permitted resume route before any local context, launch plan, or successor process can be created.

func (Store) PrepareRemoteUnderLock 

func (s Store) PrepareRemoteUnderLock(lock *SourceLock, target, requestedHarness, courier string, ssh sessionmove.SSHConfig, now time.Time) (RemoteAdmission, error)

func (Store) Resume 

func (s Store) Resume(id string, successor session.Record, now time.Time) (State, error)

func (Store) ResumeUnderLock 

func (s Store) ResumeUnderLock(lock *SourceLock, successor session.Record, now time.Time) (State, error)

func (Store) SaveRemoteReceiptUnderLock 

func (s Store) SaveRemoteReceiptUnderLock(lock *SourceLock, admission RemoteAdmission, receipt Receipt) error

SaveRemoteReceiptUnderLock is the source acknowledgement durability boundary. A crash after this write is repaired without courier redelivery.

type TargetAdmission 

type TargetAdmission struct {
	Envelope Envelope
	Digest   sessionmove.Digest
	Replay   bool
	Receipt  *Receipt
}

type TargetEvent 

type TargetEvent struct {
	SchemaVersion int       `json:"schema_version"`
	Sequence      uint64    `json:"sequence"`
	ResumeID      string    `json:"resume_id"`
	Phase         string    `json:"phase"`
	At            time.Time `json:"at"`
}

type TargetLock 

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

func (*TargetLock) Close 

func (lock *TargetLock) Close() error

func (*TargetLock) Envelope 

func (lock *TargetLock) Envelope() Envelope

func (*TargetLock) HeldForSession 

func (lock *TargetLock) HeldForSession(expectedRoot, aggregateID, digest string) bool

func (*TargetLock) RetainSessionDir 

func (lock *TargetLock) RetainSessionDir(expectedRoot, aggregateID, digest string) (*os.File, error)

type TargetStore 

type TargetStore struct{ Root string }

func NewTargetStore 

func NewTargetStore(root string) TargetStore

func (TargetStore) Acquire 

func (store TargetStore) Acquire(ctx context.Context, resumeID string, digest sessionmove.Digest) (*TargetLock, error)

func (TargetStore) Admit 

func (store TargetStore) Admit(raw []byte) (TargetAdmission, error)

func (TargetStore) AppendEventUnderLock 

func (store TargetStore) AppendEventUnderLock(lock *TargetLock, request RemoteRequest, digest sessionmove.Digest, phase string, at time.Time) (TargetEvent, error)

func (TargetStore) EnsureSuccessorContextUnderLock 

func (store TargetStore) EnsureSuccessorContextUnderLock(lock *TargetLock, request RemoteRequest, digest sessionmove.Digest, members []ReceiptMember) (string, []byte, error)

EnsureSuccessorContextUnderLock publishes the one private continuation read by the launched harness. It contains the bounded source continuation plus every deterministic target member path, pin, and target Work Log reference; neither the bytes nor the path are returned by the public receiver result.

func (TargetStore) EventsUnderLock 

func (store TargetStore) EventsUnderLock(lock *TargetLock, request RemoteRequest, digest sessionmove.Digest) ([]TargetEvent, error)

func (TargetStore) LoadReceiptUnderLock 

func (store TargetStore) LoadReceiptUnderLock(lock *TargetLock, request RemoteRequest, digest sessionmove.Digest) (*Receipt, error)

func (TargetStore) SaveReceiptUnderLock 

func (store TargetStore) SaveReceiptUnderLock(lock *TargetLock, request RemoteRequest, digest sessionmove.Digest, receipt Receipt) (Receipt, bool, error)

type Worktree 

type Worktree struct {
	Repository string `json:"repository"`
	// RepositoryRemote is the credential-free canonical fetch URL captured at
	// park time. Remote resume never rediscovers this mutable local setting.
	RepositoryRemote string `json:"repository_remote,omitempty"`
	CanonicalDir     string `json:"canonical_dir,omitempty"`
	WorktreeDir      string `json:"worktree_dir"`
	WorktreesRoot    string `json:"worktrees_root,omitempty"`
	Branch           string `json:"branch"`
	Head             string `json:"head"`
	Dirty            bool   `json:"dirty"`
	Status           string `json:"status,omitempty"`
	RemoteHead       string `json:"remote_head,omitempty"`
	// WorkLogReference binds this member to the source session's exact active
	// claim. OwnerEventID binds it to the precise source custody record, so a
	// later sequential session cannot be mistaken for the parked owner.
	WorkLogReference string `json:"work_log_reference,omitempty"`
	OwnerEventID     string `json:"owner_event_id,omitempty"`
}

Worktree is exact local evidence at park time. Dirty content is intentionally not captured; it remains in place for local resume and fails closed remotely.

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.