teamintegration

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

Documentation

Overview

Package teamintegration composes captured Coding Team results and applies an approved typed manifest without changing parent Git metadata.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalid reports malformed or incomplete integration evidence.
	ErrInvalid = errors.New("coding team integration: invalid value")
	// ErrConflict reports captured deltas that cannot be composed exactly.
	ErrConflict = errors.New("coding team integration: conflict")
	// ErrLimit reports a configured integration evidence budget exhaustion.
	ErrLimit = errors.New("coding team integration: limit exceeded")
	// ErrStale reports a changed approval or repository binding.
	ErrStale = errors.New("coding team integration: stale approval")
	// ErrConsumed reports a one-shot approval token that is no longer usable.
	ErrConsumed = errors.New("coding team integration: approval consumed")
	// ErrRecovery reports an apply state that cannot be recovered automatically.
	ErrRecovery = errors.New("coding team integration: recovery required")
	// ErrRetained reports cleanup evidence intentionally preserved for review.
	ErrRetained = errors.New("coding team integration: resource retained")
)

Functions

func SortedManifestPaths 

func SortedManifestPaths(manifest Manifest) []string

SortedManifestPaths returns an owned, stable path list for preview callers.

Types

type ApplyResult 

type ApplyResult struct {
	ID             string
	State          string
	ManifestDigest string
	Files          int
}

ApplyResult reports the terminal parent transaction without exposing private paths.

type ApprovalBinding 

type ApprovalBinding struct {
	IntegrationID     string       `json:"integration_id"`
	WorkspaceIdentity string       `json:"workspace_identity"`
	CommonIdentity    string       `json:"common_identity"`
	BranchRef         string       `json:"branch_ref"`
	HeadOID           string       `json:"head_oid"`
	StatusDigest      string       `json:"status_digest"`
	IndexDigest       string       `json:"index_digest"`
	ResourceRevision  uint64       `json:"resource_revision"`
	SelectionDigest   string       `json:"selection_digest"`
	IntegrationCommit string       `json:"integration_commit"`
	IntegrationTree   string       `json:"integration_tree"`
	ManifestDigest    string       `json:"manifest_digest"`
	DiffDigest        string       `json:"diff_digest"`
	Verification      Verification `json:"verification"`
	ExpiresAt         time.Time    `json:"expires_at"`
}

ApprovalBinding contains every value authorized by one preview.

type Artifact 

type Artifact struct {
	TaskID    string  `json:"task_id"`
	AttemptID string  `json:"attempt_id"`
	BaseOID   string  `json:"base_oid"`
	ResultOID string  `json:"result_oid"`
	ResultRef string  `json:"result_ref"`
	Base      []Entry `json:"base"`
	Result    []Entry `json:"result"`
}

Artifact is one captured Attempt delta and its immutable identity.

type AttemptBase 

type AttemptBase struct {
	CommitOID         string
	TreeOID           string
	Ref               string
	CompositionDigest string
	DependencyDigest  string
	DependencyCount   int
}

AttemptBase is the immutable Git evidence used before a Worker Worktree is created. Ref is non-empty only when this manager published an Attempt-owned multi-dependency base.

type AttemptBaseCleanupRequest 

type AttemptBaseCleanupRequest struct {
	Workspace string
	TeamID    string
	AttemptID string
	Ref       string
	CommitOID string
}

AttemptBaseCleanupRequest binds deletion to the exact derived owned ref.

type AttemptBaseRequest 

type AttemptBaseRequest struct {
	Workspace       string
	AttemptID       string
	Timestamp       time.Time
	Selection       Selection
	DirectResultOID string
}

AttemptBaseRequest identifies one deterministic dependency base for a consuming Team Attempt. DirectResultOID preserves the single-dependency fast path while still verifying the complete captured closure.

type AttemptBaseRetainedError 

type AttemptBaseRetainedError struct {
	Base  AttemptBase
	Cause error
}

AttemptBaseRetainedError reports uncertain publication after an owned ref mutation. Base is durable evidence that callers must persist before retry.

func (*AttemptBaseRetainedError) Error 

func (e *AttemptBaseRetainedError) Error() string

func (*AttemptBaseRetainedError) Unwrap 

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

type BlobReader 

type BlobReader interface {
	Blob(context.Context, string) ([]byte, error)
}

BlobReader returns exact raw Git blob bytes without filters.

type Cleanup 

type Cleanup struct {
	WorktreeRemoved       bool
	BranchDeleted         bool
	IntegrationRefDeleted bool
	JournalRemoved        bool
}

Cleanup reports exact artifact deletion. Captured Attempt result refs are outside this boundary and are never removed here.

type CleanupRequest 

type CleanupRequest struct {
	TeamID   string
	Resource Resource
}

CleanupRequest binds non-force artifact cleanup to one exact Team and prepared Integration resource.

type Composition 

type Composition struct {
	Entries    []Entry    `json:"entries"`
	Conflicts  []Conflict `json:"conflicts"`
	Duplicates int        `json:"duplicates"`
	Digest     string     `json:"digest"`
}

Composition is an immutable-by-convention composed tree and its evidence.

func Compose 

func Compose(ctx context.Context, selection Selection, limits Limits) (Composition, error)

Compose applies each dependency-ordered Attempt delta exactly once.

type Conflict 

type Conflict struct {
	TaskID    string       `json:"task_id"`
	AttemptID string       `json:"attempt_id"`
	Path      string       `json:"path"`
	Kind      ConflictKind `json:"kind"`
}

Conflict is bounded evidence that a Task delta could not be applied exactly.

type ConflictError 

type ConflictError struct {
	IntegrationID string
	AttemptIDs    []string
	Composition   Composition
}

ConflictError carries bounded deterministic composition evidence. No parent or Integration Worktree mutation has occurred when this error is returned.

func (*ConflictError) Error 

func (e *ConflictError) Error() string

func (*ConflictError) Unwrap 

func (e *ConflictError) Unwrap() error

type ConflictKind 

type ConflictKind string

ConflictKind classifies an exact entry-level composition conflict. 

const (
	ConflictUnknown      ConflictKind = "unknown"
	ConflictAddAdd       ConflictKind = "add_add"
	ConflictModifyModify ConflictKind = "modify_modify"
	ConflictDeleteModify ConflictKind = "delete_modify"
	ConflictMode         ConflictKind = "mode"
	ConflictSymlink      ConflictKind = "symlink"
	ConflictPath         ConflictKind = "file_directory"
)

Supported conflict classifications.

type Entry 

type Entry struct {
	Mode string `json:"mode"`
	OID  string `json:"oid"`
	Path string `json:"path"`
}

Entry is one exact Git tree leaf supported by the integration gate.

type FileKind 

type FileKind string

FileKind is the materialized filesystem object type. 

const (
	FileAbsent  FileKind = "absent"
	FileRegular FileKind = "regular"
	FileSymlink FileKind = "symlink"
)

Supported file kinds.

type FileState 

type FileState struct {
	Kind   FileKind `json:"kind"`
	Mode   string   `json:"mode,omitempty"`
	OID    string   `json:"oid,omitempty"`
	Size   int64    `json:"size,omitempty"`
	SHA256 string   `json:"sha256,omitempty"`
	Binary bool     `json:"binary,omitempty"`
}

FileState is one content-addressed manifest side.

type Limits 

type Limits struct {
	Entries   int
	PathBytes int
	BlobBytes int64
	TreeBytes int64
}

Limits bounds tree composition, manifest construction, and preview evidence.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns conservative production integration budgets.

type Manager 

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

Manager owns immutable Integration artifacts and process-local approvals.

func New 

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

New validates private roots and returns an Integration manager.

func (*Manager) Apply 

func (m *Manager) Apply(ctx context.Context, id, token string) (ApplyResult, error)

Apply consumes one approval before beginning the journaled parent mutation.

func (*Manager) Cleanup 

func (m *Manager) Cleanup(ctx context.Context, request CleanupRequest) (Cleanup, error)

Cleanup removes one exact clean Integration Worktree and its owned refs. It validates a terminal journal before mutation and never uses force, recursive deletion, prune, or heuristic identity recovery.

func (*Manager) CleanupAttemptBase 

func (m *Manager) CleanupAttemptBase(
	ctx context.Context,
	request AttemptBaseCleanupRequest,
) error

CleanupAttemptBase CAS-deletes only the exact derived Attempt-owned base ref. A missing ref is an idempotent success; prerequisite result refs cannot satisfy the derivation check.

func (*Manager) Discover 

func (m *Manager) Discover(ctx context.Context) ([]RecoveryCandidate, error)

Discover returns non-terminal journals without mutating their state.

func (*Manager) Prepare 

func (m *Manager) Prepare(ctx context.Context, request PrepareRequest) (Preview, error)

Prepare composes captured results without modifying the parent Workspace.

func (*Manager) PrepareAttemptBase 

func (m *Manager) PrepareAttemptBase(
	ctx context.Context,
	request AttemptBaseRequest,
) (AttemptBase, error)

PrepareAttemptBase verifies a captured dependency closure and either returns the exact single dependency result or publishes one deterministic multi-dependency base ref. It never changes the parent Worktree or index.

func (*Manager) Recover 

func (m *Manager) Recover(
	ctx context.Context,
	id string,
	action RecoveryAction,
) (ApplyResult, error)

Recover explicitly completes or rolls back one interrupted journal.

func (*Manager) Reject 

func (m *Manager) Reject(id, token string) error

Reject consumes a preview approval without modifying the parent.

func (*Manager) Resource 

func (m *Manager) Resource(id string) (Resource, error)

Resource returns private durable identity for application-state projection.

type Manifest 

type Manifest struct {
	Entries []ManifestEntry `json:"entries"`
	Added   int             `json:"added"`
	Changed int             `json:"changed"`
	Deleted int             `json:"deleted"`
	Binary  int             `json:"binary"`
	Digest  string          `json:"digest"`
}

Manifest is the canonical Team-base to Integration-tree transition.

func BuildManifest 

func BuildManifest(
	ctx context.Context,
	reader BlobReader,
	baseEntries []Entry,
	targetEntries []Entry,
	limits Limits,
) (Manifest, error)

BuildManifest creates a canonical Team-base to composed-tree manifest.

type ManifestEntry 

type ManifestEntry struct {
	Path      string    `json:"path"`
	Operation Operation `json:"operation"`
	Base      FileState `json:"base"`
	Target    FileState `json:"target"`
}

ManifestEntry is one exact parent Workspace path transition.

type Operation 

type Operation string

Operation classifies one parent Workspace path mutation. 

const (
	OperationAdd     Operation = "add"
	OperationReplace Operation = "replace"
	OperationDelete  Operation = "delete"
)

Supported manifest operations.

type Options 

type Options struct {
	GitPath          string
	ProductRoot      string
	WorktreesRoot    string
	IntegrationsRoot string
	Limits           Limits
	ApprovalTTL      time.Duration
}

Options configures the trusted Team integration boundary.

type PathState 

type PathState string

PathState classifies one recovery path against its journal evidence. 

const (
	PathBase    PathState = "base"
	PathTarget  PathState = "target"
	PathUnknown PathState = "unknown"
)

Supported recovery path classifications.

type PrepareRequest 

type PrepareRequest struct {
	Workspace string
	Selection Selection
	Verifier  Verifier
}

PrepareRequest identifies one exact parent Workspace and result selection.

type Preview 

type Preview struct {
	ID                string
	AttemptIDs        []string
	CommitOID         string
	TreeOID           string
	Manifest          Manifest
	DiffDigest        string
	Verification      Verification
	ApprovalToken     string
	ApprovalTokenHash string
	ExpiresAt         time.Time
}

Preview is the bounded evidence presented before applying parent changes.

type RecoveryAction 

type RecoveryAction string

RecoveryAction selects an explicit convergence direction. 

const (
	RecoveryComplete RecoveryAction = "complete"
	RecoveryRollback RecoveryAction = "rollback"
)

Supported explicit recovery actions.

type RecoveryCandidate 

type RecoveryCandidate struct {
	ID          string
	State       string
	Base        int
	Target      int
	Unknown     int
	Unrelated   int
	JournalHash string
}

RecoveryCandidate is a bounded read-only interrupted transaction projection.

type Resource 

type Resource struct {
	ID             string
	Workspace      workspace.Identity
	Directory      workspace.Identity
	GitDir         workspace.Identity
	CommonDir      workspace.Identity
	ObjectFormat   string
	BranchRef      string
	IntegrationRef string
	BaseOID        string
	CommitOID      string
	LockReason     string
}

Resource is the private application projection of one prepared Worktree. Frontends should use Preview instead.

type RetainedError 

type RetainedError struct {
	IntegrationID string
	Cause         error
}

RetainedError reports an artifact that was intentionally left inspectable.

func (*RetainedError) Error 

func (e *RetainedError) Error() string

func (*RetainedError) Unwrap 

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

type RolledBackError 

type RolledBackError struct {
	IntegrationID string
	Cause         error
}

RolledBackError reports an apply attempt that wrote parent paths but safely restored every one to its exact base state. The Integration artifact remains retained for inspection.

func (*RolledBackError) Error 

func (e *RolledBackError) Error() string

func (*RolledBackError) Unwrap 

func (e *RolledBackError) Unwrap() error

type Selection 

type Selection struct {
	TeamID           string     `json:"team_id"`
	ResourceRevision uint64     `json:"resource_revision"`
	BaseOID          string     `json:"base_oid"`
	Base             []Entry    `json:"base"`
	Artifacts        []Artifact `json:"artifacts"`
}

Selection is the stable dependency-closed result order chosen for one gate.

type TokenRegistry 

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

TokenRegistry owns process-local, one-shot integration approvals.

func NewTokenRegistry 

func NewTokenRegistry() *TokenRegistry

NewTokenRegistry returns an empty approval registry.

func (*TokenRegistry) Available 

func (r *TokenRegistry) Available(token string) bool

Available reports whether token is still process-local and unconsumed. The result grants no authority; Consume remains the only authorization boundary.

func (*TokenRegistry) Consume 

func (r *TokenRegistry) Consume(token string, current ApprovalBinding) error

Consume invalidates token before reporting whether current still matches it.

func (*TokenRegistry) Issue 

func (r *TokenRegistry) Issue(binding ApprovalBinding) (string, string, error)

Issue creates one opaque approval token bound to the complete preview.

func (*TokenRegistry) Reject 

func (r *TokenRegistry) Reject(token string) error

Reject invalidates a token without granting any mutation.

type Verification 

type Verification struct {
	Status             VerificationStatus `json:"status"`
	TreeOID            string             `json:"tree_oid"`
	CommandFingerprint string             `json:"command_fingerprint,omitempty"`
	OutputDigest       string             `json:"output_digest,omitempty"`
	ExitCode           int                `json:"exit_code,omitempty"`
	Signal             string             `json:"signal,omitempty"`
	DurationMillis     int64              `json:"duration_millis,omitempty"`
	Truncated          bool               `json:"truncated,omitempty"`
	Digest             string             `json:"digest"`
}

Verification is bounded evidence for one immutable Integration tree.

type VerificationRequest 

type VerificationRequest struct {
	IntegrationID string
	Workspace     workspace.Workspace
	TreeOID       string
}

VerificationRequest identifies the immutable isolated tree to validate.

type VerificationStatus 

type VerificationStatus string

VerificationStatus is the normalized validation outcome. 

const (
	VerificationNotRun         VerificationStatus = "not_run"
	VerificationPassed         VerificationStatus = "passed"
	VerificationFailed         VerificationStatus = "failed"
	VerificationTimeout        VerificationStatus = "timeout"
	VerificationApprovalNeeded VerificationStatus = "approval_required"
)

Supported verification outcomes.

type Verifier 

type Verifier interface {
	Verify(context.Context, VerificationRequest) (Verification, error)
}

Verifier runs ordinary policy-controlled validation in the isolated Integration Workspace. It must not mutate the Integration tree.

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.