teamworktree

package
v0.1.3 Latest Latest
Warning

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

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

Documentation

Overview

Package teamworktree controls Coding Team Attempt Worktrees and durable Git result refs.

The package is application infrastructure. It never accepts model-provided Git arguments and never applies a result to the parent Workspace.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalid means a request, resource, path, ref, or bound is invalid.
	ErrInvalid = errors.New("coding team worktree: invalid request")
	// ErrUnsupported means the platform cannot provide required identity/lease guarantees.
	ErrUnsupported = errors.New("coding team worktree: unsupported platform")
	// ErrLimit means a file, byte, path, Git output, or time bound was exceeded.
	ErrLimit = errors.New("coding team worktree: resource limit exceeded")
	// ErrLeaseHeld means another process owns the Team lease.
	ErrLeaseHeld = errors.New("coding team worktree: Team lease is held")
	// ErrLeaseLost means the supplied lease is closed, foreign, stale, or replaced.
	ErrLeaseLost = errors.New("coding team worktree: Team lease identity lost")
	// ErrIdentity means repository, Worktree, path, ref, or lock identity changed.
	ErrIdentity = errors.New("coding team worktree: resource identity changed")
	// ErrUnsafeRepository means Git configuration or content needs unsupported execution.
	ErrUnsafeRepository = errors.New("coding team worktree: unsafe repository")
	// ErrConflict means concurrent mutation invalidated an expected value.
	ErrConflict = errors.New("coding team worktree: concurrent mutation")
	// ErrDirty means exact raw Worktree content does not match its expected tree.
	ErrDirty = errors.New("coding team worktree: Worktree is dirty")
	// ErrRetained means cleanup intentionally preserved a resource.
	ErrRetained = errors.New("coding team worktree: resource retained")
	// ErrGit means a trusted fixed Git operation failed.
	ErrGit = errors.New("coding team worktree: Git operation failed")
)

Functions

This section is empty.

Types

type Capture 

type Capture struct {
	Resource       Resource
	CommitOID      string
	TreeOID        string
	ManifestDigest string
	Files          int
	Bytes          int64
	Added          int
	Modified       int
	Deleted        int
}

Capture is the durable result evidence published by Capture.

type CaptureRequest 

type CaptureRequest struct {
	Message string
	Time    time.Time
}

CaptureRequest supplies bounded generated commit metadata.

type Cleanup 

type Cleanup struct {
	BranchDeleted   bool
	WorktreeRemoved bool
	ResultRetained  bool
}

Cleanup reports exact resource deletion while preserving a captured result ref.

type CreateRequest 

type CreateRequest struct {
	Owner     Owner
	Workspace string
	BaseOID   string
}

CreateRequest identifies an exact parent Workspace and immutable base commit.

type FileIdentity 

type FileIdentity struct {
	Path   string
	Device uint64
	Inode  uint64
}

FileIdentity binds a canonical absolute path to one filesystem object.

type Lease 

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

Lease is retained process ownership of one Team's Worktree mutations.

func (*Lease) Close 

func (l *Lease) Close() error

Close releases process ownership. The retained metadata file remains.

type Limits 

type Limits struct {
	Files       int
	Bytes       int64
	FileBytes   int64
	PathBytes   int
	GitBytes    int64
	GitDuration time.Duration
}

Limits bounds Worktree materialization, scanning, and trusted Git execution.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns conservative production control-plane budgets.

type Manager 

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

Manager owns trusted Git sequencing and private Worktree control roots.

func New 

func New(options Options) (*Manager, error)

New validates private control roots and returns a Manager.

func (*Manager) Acquire 

func (m *Manager) Acquire(ctx context.Context, teamID team.ID, generation uint64) (*Lease, error)

Acquire obtains the non-blocking retained OS lease for one Team generation.

func (*Manager) Capture 

func (m *Manager) Capture(
	ctx context.Context,
	lease *Lease,
	resource Resource,
	request CaptureRequest,
) (Capture, error)

Capture publishes the exact raw Worktree state as one single-parent result commit and result ref without modifying the parent Workspace index.

func (*Manager) Cleanup 

func (m *Manager) Cleanup(
	ctx context.Context,
	lease *Lease,
	resource Resource,
) (Cleanup, error)

Cleanup removes only an exact clean Worktree and CAS-deletes its owned branch. A captured result ref is deliberately retained.

func (*Manager) Create 

func (m *Manager) Create(
	ctx context.Context,
	lease *Lease,
	request CreateRequest,
) (Resource, error)

Create provisions one locked no-checkout Worktree from an exact commit. A non-zero Resource returned with an error is retained recovery evidence.

func (*Manager) Inspect 

func (m *Manager) Inspect(
	ctx context.Context,
	lease *Lease,
	resource Resource,
) (Status, error)

Inspect returns bounded exact Worktree state without changing refs or index.

func (*Manager) InspectRetained 

func (m *Manager) InspectRetained(
	ctx context.Context,
	resource Resource,
) (Status, error)

InspectRetained verifies bounded exact Worktree state without acquiring or requiring the Team mutation lease. It is intended only for startup recovery discovery; callers must acquire a newer lease and call Takeover before any mutation or Worker Runtime is opened.

func (*Manager) Recover 

func (m *Manager) Recover(
	ctx context.Context,
	lease *Lease,
	request CreateRequest,
) (Resource, error)

Recover reconstructs and verifies the deterministic resource created for a request. It covers the crash window where Git creation completed before the application resource journal did. It never creates or mutates a Worktree.

func (*Manager) Takeover 

func (m *Manager) Takeover(
	ctx context.Context,
	lease *Lease,
	resource Resource,
) (Resource, error)

Takeover binds an exactly retained resource to a newly acquired higher Team lease generation. It performs no Git unlock/relock mutation.

type Options 

type Options struct {
	GitPath       string
	ProductRoot   string
	WorktreesRoot string
	LeasesRoot    string
	Limits        Limits
}

Options configures the trusted Worktree Manager.

type Owner 

type Owner struct {
	TeamID          team.ID
	MemberID        team.MemberID
	AttemptID       team.AttemptID
	LeaseGeneration uint64
}

Owner is the stable application identity of one writable Attempt resource.

type Resource 

type Resource struct {
	ID              string
	Owner           Owner
	Workspace       FileIdentity
	Directory       FileIdentity
	GitDir          FileIdentity
	CommonDir       FileIdentity
	ObjectFormat    string
	BranchRef       string
	ResultRef       string
	BaseOID         string
	ResultCommitOID string
	LockReason      string
}

Resource is the exact external identity of one Attempt Worktree.

func (Resource) TeamState 

func (r Resource) TeamState() teamstate.WorktreeResource

TeamState projects the resource into the durable application resource schema.

type RetainedError 

type RetainedError struct {
	Resource Resource
	Cause    error
}

RetainedError reports a partially completed lifecycle whose exact resource must be persisted for explicit recovery instead of force-cleaned.

func (*RetainedError) Error 

func (e *RetainedError) Error() string

func (*RetainedError) Unwrap 

func (e *RetainedError) Unwrap() []error

Unwrap makes retained errors match both ErrRetained and their root cause.

type State 

type State string

State classifies exact current Worktree state. 

const (
	StateUnchangedClean    State = "unchanged_clean"
	StateChanged           State = "changed"
	StateCapturedClean     State = "captured_clean"
	StateDirtyAfterCapture State = "dirty_after_capture"
)

Supported Worktree state classifications.

type Status 

type Status struct {
	State          State
	HeadOID        string
	TreeOID        string
	ManifestDigest string
	Files          int
	Bytes          int64
}

Status is one bounded read-only resource projection.

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.