linkage

type Commit struct {
	OID         string `json:"oid"`
	AuthorEmail string `json:"author_email"`
	CommittedAt string `json:"committed_at"`
}

type CommitRef struct {
	SHA  string
	Role Role
}

type Config struct {
	ExcludeMergeCommits bool

	// Timing controls admission and the confidence discounts for late commits
	// and long-running sessions.
	Timing TimingConfig

	// Soft files_overlap finalizer gates. Hard-link steps (commit_ref,
	// start_commit) finalize earlier and ignore these. The score they gate is
	// weighted containment — edits count fully and reads count partially — see
	// steps.FilesOverlapStep.
	FilesOverlapMinScore        float64
	FilesOverlapMinIntersection int
	// The fallback admits lower containment only with more exact edits.
	FilesOverlapFallbackScore float64
	FilesOverlapFallbackEdits int
	// FilesOverlapMinScoreMargin defines the band in which a lower-scored
	// runner-up is recorded on the winning edge.
	FilesOverlapMinScoreMargin float64

	// FilesOverlapMinConfidence and FilesOverlapMaxConfidence clamp a
	// files_overlap match's confidence: even a perfect score is a soft
	// signal next to a hard link.
	FilesOverlapMinConfidence float64
	FilesOverlapMaxConfidence float64

	// FilesOverlapMaxLinksPerCommit bounds how many sessions one commit may be
	// credited to by this step. Zero or less is unbounded. Exact ties are
	// common on small commits and the score cannot separate them, so without a
	// ceiling one commit accretes every session that clears the floor.
	FilesOverlapMaxLinksPerCommit int

	// CommitRefConfidence is the confidence assigned to a commit_ref hard
	// link.
	CommitRefConfidence float64
	// TrailerConfidence is the confidence assigned to trailer attribution.
	TrailerConfidence float64
	// StartCommitConfidence is the confidence assigned to a start_commit
	// hard link.
	StartCommitConfidence float64

	AgentAliases      map[string]string
	EnabledMatchSteps []string
}

type Edge struct {
	CommitSHA            string
	RunID                string // "" if unmatched or excluded
	AdditionalRepository bool
	Status               EdgeStatus
	Method               Method // "" if no attribution method applies
	Confidence           float64
	MatchedBy            string // matching path that finalized the edge
	TrailerAgents        []string
	Score                float64
	ScoreValid           bool // Score is only meaningful when true (files_overlap)
	CandidatesRemaining  int
	Reason               string // exclusion / unmatched reason; "" if matched
	Tie                  *TieDiagnostic
	TimeDiscount         *TimeDiscount
}

type EdgeStatus string

type EnrichedCommit struct {
	Commit
	IsMerge          bool     `json:"is_merge"`
	AncestorOID      string   `json:"ancestor_oid,omitempty"`
	CoauthoredAgents []string `json:"coauthored_agents"`
	FilesTouched     []string `json:"files_touched"`
	BranchNames      []string `json:"branch_names"`
}

type Method string

type Role string

type RunCandidate struct {
	// RunID is the tree's root session id.
	RunID string
	// AdditionalRepository identifies evidence scoped to the commit repository
	// through an active additional-repository scope.
	AdditionalRepository bool
	// Agent is the vendor that ran, e.g. "claude_code". This is what a
	// Co-Authored-By trailer names.
	Agent string
	// Source is how the tree reached us ("upload", "entire_checkpoint"). It
	// says nothing about which agent ran, which is why Agent exists.
	Source    string
	UserEmail string // "" if unknown
	Branches  []string
	StartedAt *time.Time
	EndedAt   *time.Time
	// IngestedAt is when the upload carrying this tree arrived. It stands in
	// for a missing EndedAt: an upload cannot hold activity later than itself,
	// so a session that never recorded an end is still bounded.
	IngestedAt *time.Time
	// CommitRefs are this tree's stored commit refs.
	CommitRefs []CommitRef
	// StartingCommitSHA is the role=starting ref's SHA, if any (denormalized
	// for the start_commit step; also present in CommitRefs).
	StartingCommitSHA string
	// FilesTouched is the union of the tree's read and edit evidence.
	FilesTouched []string
	// FilesEdited is the subset the tree edited.
	FilesEdited []string
}

type Step interface {
	// ID is the stable step id matched against Config.EnabledMatchSteps.
	ID() string
	Apply(commit EnrichedCommit, candidates []RunCandidate, cfg Config) StepResult
}

type StepResult struct {
	Candidates []RunCandidate
	Edges      []Edge
	// Reason explains why this step dropped candidates. The pipeline only
	// reports it when the step emptied a non-empty set, which is the one case
	// where it is the whole story.
	Reason string
}

type TieDiagnostic struct {
	Resolution TieResolution
	Peers      []TiePeer
}

type TiePeer struct {
	RunID string
	Score float64
}

type TieResolution string

type TimeDiscount struct {
	GapSeconds    float64
	WindowSeconds float64
	SyntheticEnd  bool
	Factor        float64
}

type TimingConfig struct {
	// Tolerance widens a run's [started_at, ended_at] window on the end side.
	Tolerance time.Duration
	// GapConfidenceFloor is the share of its confidence a match keeps when the
	// commit sits a full tolerance past the session's effective end.
	GapConfidenceFloor float64
	// FullConfidenceWindow is the longest session window that keeps full
	// confidence. Zero or less disables the long-window discount.
	FullConfidenceWindow time.Duration
}