teamcontrol

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 teamcontrol persists operator control intent for Coding Teams.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalid means an API value or durable record is malformed.
	ErrInvalid = errors.New("coding team control: invalid value")
	// ErrNotFound means a command or Team journal does not exist.
	ErrNotFound = errors.New("coding team control: not found")
	// ErrConflict means the expected revision is stale.
	ErrConflict = errors.New("coding team control: revision conflict")
	// ErrIdempotency means a mutation ID was reused for different semantics.
	ErrIdempotency = errors.New("coding team control: idempotency conflict")
	// ErrCorrupt means a durable journal cannot be replayed safely.
	ErrCorrupt = errors.New("coding team control: corrupt journal")
	// ErrUnsafeFile means a journal violates the private-file contract.
	ErrUnsafeFile = errors.New("coding team control: unsafe filesystem object")
	// ErrLimit means an input or durable journal exceeds configured bounds.
	ErrLimit = errors.New("coding team control: limit exceeded")
	// ErrLocked means another process owns the journal writer lock.
	ErrLocked = errors.New("coding team control: journal is locked")
	// ErrUnsupported means the platform cannot enforce the journal contract.
	ErrUnsupported = errors.New("coding team control: unsupported platform")
	// ErrAmbiguous means stable identity did not resolve to exactly one live execution.
	ErrAmbiguous = errors.New("coding team control: ambiguous target")
)

Functions

This section is empty.

Types

type Action 

type Action string

Action identifies one operator control operation. 

const (
	ActionMessage          Action = "message"
	ActionFollowUp         Action = "follow_up"
	ActionInterruptAttempt Action = "interrupt_attempt"
	ActionCancelTask       Action = "cancel_task"
	ActionRetryTask        Action = "retry_task"
	ActionCancelTeam       Action = "cancel_team"
	ActionResolveApproval  Action = "resolve_approval"
	ActionResolveQuestion  Action = "resolve_question"
	ActionRejectQuestion   Action = "reject_question"
)

Supported operator control actions.

type Command 

type Command struct {
	ID        team.CommandID `json:"id"`
	Action    Action         `json:"action"`
	Target    Target         `json:"target"`
	Text      string         `json:"text,omitempty"`
	Payload   ai.JSON        `json:"payload,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
}

Command is immutable operator intent.

type Entry 

type Entry struct {
	Command   Command         `json:"command"`
	State     State           `json:"state"`
	Resolved  *ResolvedTarget `json:"resolved,omitempty"`
	ErrorCode string          `json:"error_code,omitempty"`
	UpdatedAt time.Time       `json:"updated_at"`
}

Entry is the latest durable state of one operator command.

type InterruptedDisposition 

type InterruptedDisposition string

InterruptedDisposition describes safe restart handling for an applying entry. 

const (
	DispositionNone            InterruptedDisposition = "none"
	DispositionReconcile       InterruptedDisposition = "reconcile"
	DispositionDeliveryUnknown InterruptedDisposition = "delivery_unknown"
)

Interrupted command dispositions.

func ClassifyInterrupted 

func ClassifyInterrupted(entry Entry) InterruptedDisposition

ClassifyInterrupted returns the only safe automatic handling for an applying entry.

type Limits 

type Limits struct {
	MaxFileBytes   int64
	MaxRecordBytes int
	MaxRecords     int
	MaxTextBytes   int
	MaxListResults int
}

Limits bound a private control journal.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns production control-journal bounds.

type ListOptions 

type ListOptions struct {
	AfterRevision Revision
	Limit         int
}

ListOptions selects a bounded transition page after an exclusive revision.

type Mutation 

type Mutation struct {
	ID               team.CommandID `json:"id"`
	ExpectedRevision Revision       `json:"expected_revision"`
}

Mutation identifies one idempotent control-journal transition.

type Page 

type Page struct {
	Records   []Record
	NextAfter Revision
}

Page is one ordered control-journal transition page.

type Record 

type Record struct {
	Revision Revision `json:"revision"`
	Entry    Entry    `json:"entry"`
}

Record is one committed control-journal transition.

type ResolvedTarget 

type ResolvedTarget struct {
	TeamID          team.ID         `json:"team_id"`
	MemberID        team.MemberID   `json:"member_id,omitempty"`
	TaskID          team.TaskID     `json:"task_id,omitempty"`
	AttemptID       team.AttemptID  `json:"attempt_id,omitempty"`
	ContinuationID  continuation.ID `json:"continuation_id,omitempty"`
	SessionID       string          `json:"session_id,omitempty"`
	WorkspaceID     string          `json:"workspace_id,omitempty"`
	OwnerGeneration uint64          `json:"owner_generation,omitempty"`
}

ResolvedTarget is the exact execution identity selected before a side effect.

func ResolveCommand 

func ResolveCommand(group team.Team, resources teamstate.Snapshot, command Command) (ResolvedTarget, error)

ResolveCommand validates its domain target and resolves live actions to one execution.

func ResolveTarget 

func ResolveTarget(group team.Team, resources teamstate.Snapshot, target Target) (ResolvedTarget, error)

ResolveTarget deterministically binds stable operator identity to one live execution.

type Revision 

type Revision uint64

Revision is an optimistic control-journal version.

type State 

type State string

State is the durable lifecycle of one operator command. 

const (
	StatePending         State = "pending"
	StateApplying        State = "applying"
	StateApplied         State = "applied"
	StateRejected        State = "rejected"
	StateStale           State = "stale"
	StateDeliveryUnknown State = "delivery_unknown"
)

Operator command states.

type Store 

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

Store persists one strict append-only operator control journal per Team.

func New 

func New(directory string, limits Limits) (*Store, error)

New creates or opens a private operator control journal directory.

func (*Store) Begin 

func (s *Store) Begin(
	ctx context.Context,
	teamID team.ID,
	commandID team.CommandID,
	mutation Mutation,
	resolved ResolvedTarget,
) (Record, error)

Begin persists the exact execution identity before an external side effect.

func (*Store) Complete 

func (s *Store) Complete(
	ctx context.Context,
	teamID team.ID,
	commandID team.CommandID,
	mutation Mutation,
	state State,
	errorCode string,
) (Record, error)

Complete durably records one terminal result after applying or reconciling a command.

func (*Store) CompletePending 

func (s *Store) CompletePending(
	ctx context.Context,
	teamID team.ID,
	commandID team.CommandID,
	mutation Mutation,
	state State,
	errorCode string,
) (Record, error)

CompletePending records a command that could not resolve to an exact live execution. No external side effect has started, so only rejected and stale are valid terminal states and Resolved remains empty.

func (*Store) Dir 

func (s *Store) Dir() string

Dir returns the absolute control journal directory.

func (*Store) Get 

func (s *Store) Get(ctx context.Context, teamID team.ID, commandID team.CommandID) (Record, error)

Get returns the latest durable state of one command.

func (*Store) List 

func (s *Store) List(ctx context.Context, teamID team.ID, options ListOptions) (Page, error)

List returns a bounded page of journal transitions in revision order.

func (*Store) Pending 

func (s *Store) Pending(ctx context.Context, teamID team.ID, limit int) ([]Record, error)

Pending returns bounded current pending/applying commands in creation order.

func (*Store) Revision 

func (s *Store) Revision(ctx context.Context, teamID team.ID) (Revision, error)

Revision returns the current journal revision. A Team without a control journal has revision zero; callers may use that value for the first Submit.

func (*Store) Submit 

func (s *Store) Submit(ctx context.Context, command Command, expected Revision) (Record, error)

Submit durably creates one pending operator command.

type Target 

type Target struct {
	TeamID            team.ID        `json:"team_id"`
	MemberID          team.MemberID  `json:"member_id,omitempty"`
	TaskID            team.TaskID    `json:"task_id,omitempty"`
	ExpectedAttemptID team.AttemptID `json:"expected_attempt_id,omitempty"`
	OwnerGeneration   uint64         `json:"owner_generation,omitempty"`
}

Target carries stable logical identity supplied by the operator.

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.