events

Documentation

Overview

Package events extracts attribution candidates from event rows.

Index

• Constants
• func AddLines(m map[string]map[string]struct{}, filePath, text string)
• func BuildCandidatesFromRows(rows []EventRow, repoRoot string, eligibleFiles map[string]bool) (Candidates, EventStats)
• func ExtractClaudeActions(raw []byte, repoRoot string) (fileLines map[string]map[string]struct{}, bashCommands []string)
• func ExtractDeletedPaths(cmd, repoRoot string) []string
• func ExtractProviderFileTouches(toolUses, repoRoot string) []string
• func HasEditOrWrite(toolUses string) bool
• func HasProviderFileEdit(toolUses string) bool
• func NormalizePath(filePath, repoRoot string) string
• func SuppressInferredDeletions(cands *Candidates, deltas *DeltaCandidates)
• type Candidates
• type DeltaBlobGetter
• type DeltaCandidates
  • func BuildDeltaCandidates(ctx context.Context, links []DeltaLink, blobs DeltaBlobGetter) (*DeltaCandidates, error)
• type DeltaClaimGroup
• type DeltaDiagnostics
• type DeltaLink
• type EventRow
• type EventStats
• type LineStamp

Constants

const (
	DeltaRejectBadHash         = "bad_hash"
	DeltaRejectDivergentHashes = "divergent_hashes"
	DeltaRejectBlobUnavailable = "blob_unavailable"
	DeltaRejectHashMismatch    = "hash_mismatch"
	DeltaRejectParseFailure    = "parse_failure"
	DeltaRejectEventBinding    = "event_binding"
	DeltaRejectIncompleteLinks = "incomplete_links"
	DeltaRejectProviderBinding = "provider_binding"
	DeltaRejectConcurrentGroup = "concurrent_group"
	DeltaRejectAmbiguousActors = "ambiguous_actors"
	DeltaRejectPartial         = "partial"
	DeltaRejectCrossGroupEvent = "cross_group_event"
)

Stable rejection reasons for excluded delta groups.

Functions

func AddLines

func AddLines(m map[string]map[string]struct{}, filePath, text string)

AddLines splits text into lines and inserts each trimmed, non-blank line into the set for the given file path.

func BuildCandidatesFromRows

func BuildCandidatesFromRows(rows []EventRow, repoRoot string, eligibleFiles map[string]bool) (Candidates, EventStats)

BuildCandidatesFromRows extracts attribution candidates from event rows. A non-nil eligibleFiles map limits which files contribute evidence.

func ExtractClaudeActions

func ExtractClaudeActions(raw []byte, repoRoot string) (fileLines map[string]map[string]struct{}, bashCommands []string)

ExtractClaudeActions parses a Claude-format assistant payload and extracts: - fileLines: map of repo-relative file paths to sets of trimmed lines (from Edit/Write tools) - bashCommands: shell commands from Bash tool calls

func ExtractDeletedPaths

func ExtractDeletedPaths(cmd, repoRoot string) []string

ExtractDeletedPaths extracts file paths from a shell command containing "rm". Returns repo-relative paths.

func ExtractProviderFileTouches

func ExtractProviderFileTouches(toolUses, repoRoot string) []string

ExtractProviderFileTouches parses the tool_uses JSON and returns repo-relative file paths that the AI touched. Paths that look absolute are relativized against repoRoot via NormalizePath so the scorer's diff-keyed lookup (which uses git's repo-relative paths) matches regardless of whether the hook layer stored an absolute path. Paths that already look relative pass through unchanged so providers that emit subdir-relative paths in their hook payloads (and whose hook payload `cwd` matched the repo root at emit time) keep their existing behavior.

func HasEditOrWrite

func HasEditOrWrite(toolUses string) bool

HasEditOrWrite returns true if the tool_uses JSON contains an Edit or Write tool call. Used as a fast pre-filter before payload loading.

func HasProviderFileEdit

func HasProviderFileEdit(toolUses string) bool

HasProviderFileEdit returns true if the tool_uses JSON indicates a provider file edit event. Matches tool names from providers that report file modifications without an accompanying line-level payload: Cursor, Copilot, Kiro, Gemini, and Codex apply_patch operations whose envelope produced no new content (deletions, empty-file adds, the source half of a rename).

func NormalizePath

func NormalizePath(filePath, repoRoot string) string

NormalizePath converts a file path to the repo-relative, forward-slash form `git diff` produces. Accepts absolute paths (from Claude's Edit/Write tools) and already-repo-relative paths (from Bash `rm` arguments). Handles MSYS-style paths (/c/workspace/...) from Claude Code on Windows.

func SuppressInferredDeletions

func SuppressInferredDeletions(cands *Candidates, deltas *DeltaCandidates)

SuppressInferredDeletions removes command-inferred touches when a verified delta records the same deletion. Explicit touches remain.

Types

type Candidates

type Candidates struct {
	AILines              map[string]map[string]struct{}            // file -> set of trimmed lines
	LineProviders        map[string]map[string]map[string]struct{} // file -> line -> set of providers that emitted that line
	LineStamps           map[string]map[string][]LineStamp         // file -> line -> direct witnesses
	ProviderTouchedFiles map[string]string                         // file -> provider (file-level, includes deletions)
	FileProvider         map[string]string                         // file -> provider (line-level; last-writer-wins, see LineProviders for per-line breakdown)
	ProviderModel        map[string]string                         // provider -> model
	// InferredDeletions identifies file touches inferred from bash commands.
	InferredDeletions map[string]string // file -> provider
	// ExplicitTouches retains the latest file-edit witness so suppression
	// can restore it after removing an inferred deletion.
	ExplicitTouches map[string]LineStamp
}

Candidates holds line and file evidence extracted from events. LineProviders preserves per-line ownership; FileProvider is the fallback for callers without per-line data.

type DeltaBlobGetter

type DeltaBlobGetter interface {
	Get(ctx context.Context, hash string) ([]byte, error)
}

DeltaBlobGetter loads a CAS blob by hash.

type DeltaCandidates

type DeltaCandidates struct {
	Claims map[string][]DeltaClaimGroup // file -> claim groups, capture order
	// Touched contains files without usable line evidence.
	Touched map[string][]string // file -> providers, first-seen order
	// Deleted contains files removed by complete deltas.
	Deleted map[string][]string // file -> providers, first-seen order
	Diags   DeltaDiagnostics
}

DeltaCandidates holds verified evidence for one attribution window. Claims and providers retain first-seen order.

func BuildDeltaCandidates

func BuildDeltaCandidates(ctx context.Context, links []DeltaLink, blobs DeltaBlobGetter) (*DeltaCandidates, error)

BuildDeltaCandidates verifies and classifies tool-delta links. Invalid, incomplete, partial, concurrent, or ambiguous groups contribute nothing. Linked events must exactly match the delta and its actor providers.

Cancellation returns an error rather than partial candidates.

type DeltaClaimGroup

type DeltaClaimGroup struct {
	GroupID  string
	Provider string
	// Recency of the latest member event.
	Ts        int64
	InsertSeq int64
	EventID   string
	Lines     []string // ordered added lines, hunk order
}

DeltaClaimGroup contains one group's ordered claims for a file.

type DeltaDiagnostics

type DeltaDiagnostics struct {
	GroupsSeen     int
	GroupsEligible int
	Rejected       map[string]int
}

DeltaDiagnostics counts eligible and rejected groups.

type DeltaLink

type DeltaLink struct {
	EventID      string
	EvidenceHash string
	GroupID      string
	Provider     string
	Ts           int64
	InsertSeq    int64
}

DeltaLink binds a tool-delta blob to an event and its session provider, with the event's recency for winner selection.

type EventRow

type EventRow struct {
	Provider    string
	Role        string // "assistant", "user", "tool", etc.
	ToolUses    string // raw JSON from the tool_uses column
	PayloadHash string // CAS hash (for diagnostics, not used for loading)
	Payload     []byte // pre-loaded by the caller; nil if unavailable
	Model       string // LLM model name (e.g. "opus 4.6")
	// Identity and recency used to resolve competing evidence.
	EventID   string
	Ts        int64
	InsertSeq int64
}

EventRow contains the event data needed to build candidates.

type EventStats

type EventStats struct {
	EventsConsidered int
	EventsAssistant  int
	PayloadsLoaded   int
	AIToolEvents     int
}

EventStats collects diagnostic counters from event processing. Each counter is independently meaningful; callers combine EventStats with scoring stats to produce the full diagnostics.

type LineStamp

type LineStamp struct {
	Provider  string
	Ts        int64
	InsertSeq int64
	EventID   string
}

LineStamp is one direct witness for a line; recency compares by (Ts, InsertSeq, EventID).