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 ¶
- Variables
- type Capture
- type CaptureRequest
- type Cleanup
- type CreateRequest
- type FileIdentity
- type Lease
- type Limits
- type Manager
- func (m *Manager) Acquire(ctx context.Context, teamID team.ID, generation uint64) (*Lease, error)
- func (m *Manager) Capture(ctx context.Context, lease *Lease, resource Resource, request CaptureRequest) (Capture, error)
- func (m *Manager) Cleanup(ctx context.Context, lease *Lease, resource Resource) (Cleanup, error)
- func (m *Manager) Create(ctx context.Context, lease *Lease, request CreateRequest) (Resource, error)
- func (m *Manager) CreateSubagent(ctx context.Context, request SubagentRequest) (SubagentWorktree, error)
- func (m *Manager) Inspect(ctx context.Context, lease *Lease, resource Resource) (Status, error)
- func (m *Manager) InspectRetained(ctx context.Context, resource Resource) (Status, error)
- func (m *Manager) Recover(ctx context.Context, lease *Lease, request CreateRequest) (Resource, error)
- func (m *Manager) Takeover(ctx context.Context, lease *Lease, resource Resource) (Resource, error)
- type Options
- type Owner
- type Resource
- type RetainedError
- type State
- type Status
- type SubagentRequest
- type SubagentWorktree
Constants ¶
This section is empty.
Variables ¶
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 ¶
CaptureRequest supplies bounded generated commit metadata.
type CreateRequest ¶
CreateRequest identifies an exact parent Workspace and immutable base commit.
type FileIdentity ¶
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.
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 (*Manager) Acquire ¶
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 ¶
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) CreateSubagent ¶ added in v0.1.9
func (m *Manager) CreateSubagent( ctx context.Context, request SubagentRequest, ) (SubagentWorktree, error)
CreateSubagent provisions one preserved, linked Worktree for a child execution. The Worktree starts at the workspace's current HEAD and is locked under this package's control reason.
The Worktree is never removed by this package. The caller reports its directory and keeps it for inspection after the child finishes, so the child can work — and commit — without touching the parent working tree. A partial resource is returned with an error when Git created the directory but a later identity check failed, which is the same recovery evidence an Attempt Worktree reports.
func (*Manager) Inspect ¶
Inspect returns bounded exact Worktree state without changing refs or index.
func (*Manager) InspectRetained ¶
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.
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 ¶
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 Status ¶
type Status struct {
State State
HeadOID string
TreeOID string
ManifestDigest string
Files int
Bytes int64
}
Status is one bounded read-only resource projection.
type SubagentRequest ¶ added in v0.1.9
type SubagentRequest struct {
// ID is the child identity. It names the Worktree directory.
ID string
// Workspace is the canonical parent workspace path. It must be the Git top
// level and must already have one commit.
Workspace string
}
SubagentRequest identifies one preserved child Worktree.
type SubagentWorktree ¶ added in v0.1.9
type SubagentWorktree struct {
ID string
Workspace FileIdentity
Directory FileIdentity
GitDir FileIdentity
CommonDir FileIdentity
BranchRef string
BaseOID string
LockReason string
}
SubagentWorktree is the exact external identity of one preserved child Worktree. It carries no result ref and no capture state: the child's work is preserved in place on its own branch rather than committed into a durable integration result.