implementations

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SourceAuto   = "auto"
	SourceManual = "manual"

	// InProgressTTL is how long a generation_in_progress_at marker is
	// considered fresh before being treated as stale (crashed process).
	InProgressTTL = 5 * time.Minute
)
View Source 
const (
	// DormancyTimeout is how long an implementation can be idle before
	// transitioning from active to dormant.
	DormancyTimeout = 60 * time.Minute

	// ReconcileBatch is the maximum number of observations processed per
	// reconciliation pass.
	ReconcileBatch = 100

	// MaxRetryAttempts is how many times a failed observation is retried
	// before it's considered permanently failed.
	MaxRetryAttempts = 3

	// DeferMaxAttempts is how many reconciliation cycles a child observation
	// waits for its parent before being processed as standalone.
	DeferMaxAttempts int64 = 1
)

Variables

This section is empty.

Functions

func ApplySuggestion 

func ApplySuggestion(ctx context.Context, in ApplySuggestionInput) error

ApplySuggestion writes the suggested title and summary to an implementation, along with source metadata for manual-override protection.

func ClearGenerationInProgress added in v0.2.1 

func ClearGenerationInProgress(ctx context.Context, h *impldb.Handle, implID string)

ClearGenerationInProgress clears the in-progress marker. Called by the background command on completion (in a defer).

func Close 

func Close(ctx context.Context, implID string) error

Close sets an implementation's state to 'closed'. Idempotent.

func GitDetectBranch 

func GitDetectBranch(ctx context.Context, repoPath string) string

GitDetectBranch detects the current branch using git CLI. Safe to call from the worker (off hot path).

func LinkCommit 

func LinkCommit(ctx context.Context, in LinkCommitInput) error

LinkCommit manually attaches a commit to an implementation. Uses attach_rule="explicit_link" which bypasses the partial unique index.

func MarkGenerationInProgress added in v0.2.1 

func MarkGenerationInProgress(ctx context.Context, h *impldb.Handle, implID string) error

MarkGenerationInProgress sets the generation_in_progress_at marker in metadata_json. Called by the worker before spawning the background command.

func ShouldAutoSummarize added in v0.2.1 

func ShouldAutoSummarize(ctx context.Context, h *impldb.Handle, implID string, opts ShouldAutoSummarizeOpts) (bool, string)

ShouldAutoSummarize checks whether a background implementation summary should be generated for the given implementation. Returns (true, "") if generation should proceed, or (false, reason) if it should be skipped.

func WriteImplementationMeta added in v0.2.1 

func WriteImplementationMeta(meta ImplementationMeta) (sql.NullString, error)

WriteImplementationMeta serializes metadata back to a sql.NullString, preserving unknown keys from the original JSON.

Types

type ApplySuggestionInput added in v0.2.1 

type ApplySuggestionInput struct {
	ImplementationID string
	Title            string
	Summary          string
	Source           string // SourceAuto or SourceManual
	RepoCount        int    // current repo count (for auto freshness tracking)
}

ApplySuggestionInput contains parameters for writing a suggestion.

type AttachCommitInput 

type AttachCommitInput struct {
	RepoPath   string
	CommitHash string
}

AttachCommitInput contains the parameters for linking a commit to an implementation.

type BranchDetector 

type BranchDetector func(ctx context.Context, repoPath string) string

BranchDetector returns the current git branch for a repo path. Returns "" if detection fails or is unavailable.

type CommitDetail 

type CommitDetail struct {
	CanonicalPath string `json:"canonical_path"`
	DisplayName   string `json:"display_name"`
	CommitHash    string `json:"commit_hash"`
	Subject       string `json:"subject,omitempty"`
	AttachedAt    int64  `json:"attached_at"`
	AttachRule    string `json:"attach_rule"`
}

CommitDetail is a commit reference in the detail view.

type GenerateTextFunc 

type GenerateTextFunc func(ctx context.Context, prompt string) (*llm.GenerateTextResult, error)

GenerateTextFunc abstracts the LLM call for testing.

type ImplementationDetail 

type ImplementationDetail struct {
	ImplementationID  string            `json:"implementation_id"`
	Title             string            `json:"title,omitempty"`
	Summary           string            `json:"summary,omitempty"`
	State             string            `json:"state"`
	CreatedAt         int64             `json:"created_at"`
	LastActivityAt    int64             `json:"last_activity_at"`
	Repos             []RepoDetail      `json:"repos"`
	RepoAttribution   []RepoAttribution `json:"repo_attribution,omitempty"`
	Sessions          []SessionDetail   `json:"sessions"`
	Commits           []CommitDetail    `json:"commits"`
	Timeline          []TimelineEntry   `json:"timeline"`
	TotalTokensIn     int64             `json:"total_tokens_in"`
	TotalTokensOut    int64             `json:"total_tokens_out"`
	TotalTokensCached int64             `json:"total_tokens_cached"`
}

ImplementationDetail is the full view of an implementation with timeline.

func GetDetail 

func GetDetail(ctx context.Context, implID string) (*ImplementationDetail, error)

GetDetail loads the full implementation detail with cross-repo timeline.

type ImplementationMeta added in v0.2.1 

type ImplementationMeta struct {
	Summary                string `json:"summary,omitempty"`
	TitleSource            string `json:"title_source,omitempty"`              // "auto" or "manual"
	SummarySource          string `json:"summary_source,omitempty"`            // "auto" or "manual"
	GeneratedRepoCount     int    `json:"generated_repo_count,omitempty"`      // repo count at last auto-generation
	GeneratedAt            int64  `json:"generated_at,omitempty"`              // unix ms of last auto-generation
	GenerationInProgressAt int64  `json:"generation_in_progress_at,omitempty"` // unix ms, set before spawning
	// contains filtered or unexported fields
}

ImplementationMeta is the structured content of implementations.metadata_json. Unknown keys in the JSON are preserved across read/write cycles.

func ReadImplementationMeta added in v0.2.1 

func ReadImplementationMeta(raw sql.NullString) ImplementationMeta

ReadImplementationMeta parses metadata_json into a structured type, preserving unknown keys for round-trip safety.

func (ImplementationMeta) IsGenerationInProgress added in v0.2.1 

func (m ImplementationMeta) IsGenerationInProgress() bool

IsGenerationInProgress returns true if a background generation was recently started and hasn't completed yet.

func (ImplementationMeta) IsManuallyEdited added in v0.2.1 

func (m ImplementationMeta) IsManuallyEdited() bool

IsManuallyEdited returns true if either the title or summary was manually set by the user. When true, auto-generation should skip.

type LinkCommitInput 

type LinkCommitInput struct {
	ImplementationID string
	CommitHash       string
	RepoPath         string // repo containing the commit
}

LinkCommitInput contains the parameters for linking a commit.

type LinkSessionInput 

type LinkSessionInput struct {
	ImplementationID string
	SessionID        string // Semantica session UUID, prefix, or provider_session_id
	RepoPath         string // optional: repo to search for the session
	Force            bool   // skip confirmation when moving between implementations
}

LinkSessionInput contains the parameters for linking a session.

type LinkSessionResult 

type LinkSessionResult struct {
	LinkedProvider  string
	LinkedSessionID string
	MovedFrom       string // previous implementation ID, if moved
}

LinkSessionResult reports what happened.

func LinkSession 

func LinkSession(ctx context.Context, in LinkSessionInput) (*LinkSessionResult, error)

LinkSession manually attaches a session to an implementation.

type ListInput 

type ListInput struct {
	Limit         int64
	All           bool // include old dormant, closed, and single-repo
	IncludeSingle bool // include single-repo implementations
}

ListInput controls which implementations are returned.

type ListItem 

type ListItem struct {
	ImplementationID string        `json:"implementation_id"`
	Title            string        `json:"title,omitempty"`
	State            string        `json:"state"`
	RepoCount        int64         `json:"repo_count"`
	CommitCount      int64         `json:"commit_count"`
	LastActivityAt   int64         `json:"last_activity_at"`
	Repos            []RepoSummary `json:"repos"`
}

ListItem is one row in the implementations listing.

type ListResult 

type ListResult struct {
	Items []ListItem `json:"items"`
	Total int        `json:"total"`
}

ListResult wraps the list output.

func List 

func List(ctx context.Context, in ListInput) (*ListResult, error)

List returns implementations matching the filter criteria.

type MergeResult 

type MergeResult struct {
	TargetID string
	SourceID string
}

MergeResult reports what was moved.

func Merge 

func Merge(ctx context.Context, targetIDInput, sourceIDInput string) (*MergeResult, error)

Merge moves all sessions, commits, repos, and branches from source into target. Source is closed. Target keeps its title, state, and created_at. Origin role preservation: if target has no origin but source does, the origin transfers via the repo upsert logic.

type ReconcileResult 

type ReconcileResult struct {
	MarkedDormant    int64
	Processed        int
	DeferredResolved int
	Retried          int
	Errors           []error
}

ReconcileResult summarizes what happened during a reconciliation pass.

type Reconciler 

type Reconciler struct {
	// DetectBranch returns the current git branch for a repo path.
	// Defaults to git CLI detection if nil. Injected for testing.
	DetectBranch BranchDetector
}

Reconciler processes pending observations and materializes implementations.

func (*Reconciler) AttachCommit 

func (r *Reconciler) AttachCommit(ctx context.Context, h *impldb.Handle, in AttachCommitInput) error

AttachCommit links a commit to the implementation that owns the session(s) active at commit time. Defaults to one implementation per commit. The partial unique index rejects duplicates for non-explicit rules.

func (*Reconciler) Reconcile 

func (r *Reconciler) Reconcile(ctx context.Context, h *impldb.Handle) (*ReconcileResult, error)

Reconcile processes pending observations and materializes implementations. Idempotent: safe to call concurrently from multiple workers.

type RepoAttribution 

type RepoAttribution struct {
	CanonicalPath string  `json:"canonical_path"`
	DisplayName   string  `json:"display_name"`
	AIPercentage  float64 `json:"ai_percentage"`
	CommitCount   int     `json:"commit_count"`
}

RepoAttribution is the averaged cached AI attribution for a repo's commits within one implementation.

type RepoDetail 

type RepoDetail struct {
	CanonicalPath string `json:"canonical_path"`
	DisplayName   string `json:"display_name"`
	Role          string `json:"role"`
	FirstSeenAt   int64  `json:"first_seen_at"`
	SessionCount  int    `json:"session_count"`
}

RepoDetail extends RepoSummary with more info for the detail view.

type RepoSummary 

type RepoSummary struct {
	DisplayName string `json:"display_name"`
	Role        string `json:"role"`
}

RepoSummary is a lightweight repo reference for the list view.

type SessionDetail 

type SessionDetail struct {
	Provider          string `json:"provider"`
	ProviderSessionID string `json:"provider_session_id"`
	SourceProjectPath string `json:"source_project_path,omitempty"`
	AttachRule        string `json:"attach_rule"`
	AttachedAt        int64  `json:"attached_at"`
}

SessionDetail is a session reference in the detail view.

type ShouldAutoSummarizeOpts added in v0.2.1 

type ShouldAutoSummarizeOpts struct {
	// SkipInProgressCheck disables the duplicate-work guard. Set to true
	// when called from inside the background job itself, which already
	// owns the in-progress marker.
	SkipInProgressCheck bool
}

ShouldAutoSummarizeOpts controls which checks ShouldAutoSummarize runs.

type SuggestBatchResult 

type SuggestBatchResult struct {
	Titles    []llm.TitleSuggestion `json:"titles,omitempty"`
	Merges    []llm.MergeSuggestion `json:"merges,omitempty"`
	Provider  string                `json:"provider,omitempty"`
	Model     string                `json:"model,omitempty"`
	Truncated bool                  `json:"truncated,omitempty"` // true if input was capped
	Total     int                   `json:"total,omitempty"`     // total active+dormant count
	Analyzed  int                   `json:"analyzed,omitempty"`  // how many were sent to LLM
}

SuggestBatchResult holds title and merge suggestions across implementations.

type SuggestResult 

type SuggestResult struct {
	Title    string `json:"title"`
	Summary  string `json:"summary"`
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
}

SuggestResult holds the LLM-generated suggestions for a single implementation.

type SuggestService 

type SuggestService struct {
	GenerateText GenerateTextFunc
}

SuggestService generates LLM-powered suggestions for implementations.

func NewSuggestService 

func NewSuggestService() *SuggestService

NewSuggestService creates a SuggestService using the real LLM pipeline.

func (*SuggestService) SuggestBatch 

func (s *SuggestService) SuggestBatch(ctx context.Context) (*SuggestBatchResult, error)

SuggestBatch generates title suggestions for untitled implementations and merge candidates across all active/dormant implementations.

func (*SuggestService) SuggestForImplementation 

func (s *SuggestService) SuggestForImplementation(ctx context.Context, implID string) (*SuggestResult, error)

SuggestForImplementation generates a title and summary for a single implementation.

type TimelineEntry 

type TimelineEntry struct {
	Timestamp int64  `json:"timestamp"`
	RepoName  string `json:"repo_name"`
	Kind      string `json:"kind"` // "session_start", "edit", "tool", "commit", "event"
	Summary   string `json:"summary"`
	FilePath  string `json:"file_path,omitempty"`
	FileOp    string `json:"file_op,omitempty"`
	CrossRepo bool   `json:"cross_repo"` // true when repo changed from previous entry
}

TimelineEntry is one event in the cross-repo timeline.

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.