Documentation
¶
Overview ¶
Package sessioncorrelate derives the evidence the commit matcher needs from a session tree: repo-relative file paths, role-tagged commit refs, and the branches and working directories the tree was seen in.
It never mutates the graph. Rewriting file paths inside the session would make the stored session stop saying what the tool actually reported, and every consumer would inherit the matcher's view of a path. Vendor truth stays in the session package and the matcher-shaped view is a separate value the ingest layer stores beside it.
The package is pure: no I/O, no database, and no mapper packages. The only vendor knowledge in it is the attribute-key table in keys.go, a per-vendor hook keyed by slug.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithoutAgentWorktree ¶
WithoutAgentWorktree removes a leading agent worktree such as {.claude,.agents}/worktrees/<name>/ from a repo-relative path, as relativization does, or returns false when nothing is left. Callers use it to compare paths stored before that prefix was removed.
Types ¶
type CommitRef ¶
type CommitRef struct {
SHA string
Role Role
ObservedAt *time.Time
// ToolUseID owns the observation when a tool call produced it, and is nil
// for evidence that came from session metadata rather than from a tool.
ToolUseID *string
}
CommitRef is one role-tagged commit SHA the tree evidenced. SHA is lowercase: see commitRefSet.add.
type FileEvidence ¶
FileEvidence is one repo-relative path the tree touched, and how.
type Option ¶
type Option func(*options)
Option supplies evidence the source recorded beside the graph rather than inside it.
func WithCloneRoots ¶
WithCloneRoots gives PathResolver the absolute directories of the clone's checkouts (its main working tree, its worktrees and the directories it used to live at). Correlate ignores it.
func WithEditedFiles ¶
WithEditedFiles adds repository-relative paths the source reported as changed while this session ran — Entire's session metadata files_touched. They become `edit` evidence in their own right, and they anchor relativization for a session that recorded no working directory.
The list is a working-tree diff, not a record of the session's tool calls, so the caller decides when it may stand as evidence. The Entire ingest supplies it only for a session with no native file evidence of its own, and never when a sibling session in the checkpoint reports the identical list.
func WithFileAnchors ¶
WithFileAnchors supplies repository-relative paths only for relativizing native file touches; the paths do not become evidence themselves.
func WithRepositoryRoots ¶
func WithRepositoryRoots(primaryRepository string, repositories ...RepositoryRoots) Option
WithRepositoryRoots enables strict cross-repository classification through roots already validated and authorized by the ingest layer.
type PathResolver ¶
type PathResolver struct {
// contains filtered or unexported fields
}
PathResolver makes individual file touches repo-relative by the same rules Correlate applies to its file evidence: recorded repository and worktree roots, then the touch's own session cwd values, then the rest of the tree's (longest wins in each), never cutting a cwd-relative path deeper than an in-repo agent worktree the tree worked in, then the anchor rule, with a leading agent worktree removed. Touches that WithRepositoryRoots moves to another repository do not resolve. Consumers that need per-touch paths, not the tree's deduplicated file list, use it so the two views cannot disagree about a path.
WithCloneRoots narrows it further for a caller that knows the checkouts the repository was worked in: an absolute path then resolves only inside one of them, cut at the longest and with a leading agent worktree removed, and a relative one only once joined with the working directory it was recorded in, so a file beside the clone is never mistaken for one in it.
func NewPathResolver ¶
func NewPathResolver(graph *session.Graph, vendor string, opts ...Option) *PathResolver
NewPathResolver prepares relativization for graph. vendor and opts mean what they mean for Correlate; WithEditedFiles paths only anchor here.
func (*PathResolver) Dirs ¶
func (r *PathResolver) Dirs() []string
Dirs returns every working directory and recorded root in the tree.
func (*PathResolver) Roots ¶
func (r *PathResolver) Roots() []string
Roots returns the tree's recorded repository and worktree roots, which relativization tries before any working directory.
type RepositoryResult ¶
type RepositoryResult struct {
RepositoryID string
Files []FileEvidence
CommitRefs []CommitRef
Branches []string
WorkingDirs []string
}
RepositoryResult is matcher evidence proven to belong to one additional repository.
type RepositoryRoots ¶
RepositoryRoots binds verified roots to a repository for one upload.
type Result ¶
type Result struct {
Files []FileEvidence
CommitRefs []CommitRef
Branches []string
WorkingDirs []string
Warnings []string
AdditionalRepositories []RepositoryResult
}
Result is everything the matcher may read about a session tree. Fail closed: an input this package cannot confidently interpret becomes a warning, never an invented file, branch, or commit ref.
type Role ¶
type Role string
Role is how a session relates to a commit SHA: created it, mentioned it, checked it out, and so on. It is defined here rather than imported from the matcher or a session store so this package stays decoupled from both; the ingest layer translates at the persist boundary.
Source Files