checkpoint

type Attribution struct {
	CalculatedAt      time.Time `json:"calculated_at"`
	AgentLines        int       `json:"agent_lines"`              // Lines added by agent that remain in the commit
	AgentRemoved      int       `json:"agent_removed"`            // Lines removed by agent that remain removed in the commit
	HumanAdded        int       `json:"human_added"`              // Lines added by human (excluding modifications)
	HumanModified     int       `json:"human_modified"`           // Lines modified by human (estimate: min(added, removed))
	HumanRemoved      int       `json:"human_removed"`            // Lines removed by human (excluding modifications)
	TotalCommitted    int       `json:"total_committed"`          // Net additions in commit (legacy additions-focused metric)
	TotalLinesChanged int       `json:"total_lines_changed"`      // Total committed line changes (adds + modifies + removes)
	AgentPercentage   float64   `json:"agent_percentage"`         // (agent_lines + agent_removed) / total_lines_changed * 100
	MetricVersion     int       `json:"metric_version,omitempty"` // 0/absent = legacy (additions-only %), 2 = changed-lines %
}

type CheckpointAttribution struct {
	CheckpointID id.CheckpointID
	Attribution  *Attribution
}

type CheckpointInfo struct {
	// CheckpointID is the stable 12-hex-char identifier
	CheckpointID id.CheckpointID

	// SessionID is the session identifier (most recent session for multi-session checkpoints)
	SessionID string

	// CreatedAt is when the checkpoint was created
	CreatedAt time.Time

	// CheckpointsCount is the aggregate displayed "steps" count across sessions:
	// the sum of per-session prompt-window counts. Despite the historical name,
	// it is not a count of checkpoint records.
	CheckpointsCount int

	// FilesTouched are files modified during all sessions
	FilesTouched []string

	// Agent identifies the agent that created this checkpoint
	Agent types.AgentType

	// IsTask indicates if this is a task checkpoint
	IsTask bool

	// ToolUseID is the tool use ID for task checkpoints
	ToolUseID string

	// Multi-session support
	SessionCount int      // Number of sessions (1 if single session)
	SessionIDs   []string // All session IDs that contributed

	// Imported is true when this checkpoint was imported from pre-existing
	// agent history (Kind == "imported"): read-only and commit-less.
	Imported bool
}

type CheckpointReader interface {
	Read(ctx context.Context, checkpointID id.CheckpointID) (*CheckpointSummary, error)
	List(ctx context.Context) ([]CheckpointInfo, error)
}

type CheckpointSummary struct {
	CLIVersion          string             `json:"cli_version,omitempty"`
	CheckpointVersion   string             `json:"checkpoint_version,omitempty"`
	CheckpointID        id.CheckpointID    `json:"checkpoint_id"`
	Strategy            string             `json:"strategy"`
	Branch              string             `json:"branch,omitempty"`
	CheckpointsCount    int                `json:"checkpoints_count"`
	FilesTouched        []string           `json:"files_touched"`
	Sessions            []SessionFilePaths `json:"sessions"`
	TokenUsage          *types.TokenUsage  `json:"token_usage,omitempty"`
	CombinedAttribution *Attribution       `json:"combined_attribution,omitempty"`

	// HasReview is the umbrella "any review happened" flag: true when at least
	// one session in this checkpoint has a review-kind Kind (currently
	// "agent_review"). When new review kinds are introduced they should also
	// cause this flag to be set so callers can keep asking "was this reviewed
	// in any way?" without caring about the variant.
	HasReview bool `json:"has_review,omitempty"`

	// HasInvestigation is the umbrella "any investigation happened" flag:
	// true when at least one session in this checkpoint has an
	// investigate-kind Kind (currently "agent_investigate"). When new
	// investigate kinds are introduced they should also cause this flag to
	// be set so callers can keep asking "was this investigated in any way?"
	// without caring about the variant.
	HasInvestigation bool `json:"has_investigation,omitempty"`

	// Imported is true when this checkpoint was imported from pre-existing
	// agent history (a session with Kind == "imported"): read-only and
	// commit-less.
	Imported bool `json:"imported,omitempty"`
}

type CodeLearning struct {
	Path    string `json:"path"`               // File path
	Line    int    `json:"line,omitempty"`     // Start line number
	EndLine int    `json:"end_line,omitempty"` // End line for ranges (optional)
	Finding string `json:"finding"`            // What was learned
}

type LearningsSummary struct {
	Repo     []string       `json:"repo"`     // Codebase-specific patterns/conventions
	Code     []CodeLearning `json:"code"`     // File/module specific findings
	Workflow []string       `json:"workflow"` // General dev practices
}

type Metadata struct {
	CLIVersion       string          `json:"cli_version,omitempty"`
	CheckpointID     id.CheckpointID `json:"checkpoint_id"`
	SessionID        string          `json:"session_id"`
	Strategy         string          `json:"strategy"`
	CreatedAt        time.Time       `json:"created_at"`
	Branch           string          `json:"branch,omitempty"` // Branch where checkpoint was created (empty if detached HEAD)
	CheckpointsCount int             `json:"checkpoints_count"`
	// SaveStepCount is the number of SaveStep-recorded steps for this session.
	// Honest "real checkpoint work happened" signal (0 = commit-only/fallback
	// session), kept separate from the displayed CheckpointsCount prompt count.
	// Added after CheckpointsCount stopped being a reliable did-SaveStep-run signal.
	SaveStepCount int      `json:"save_step_count,omitempty"`
	FilesTouched  []string `json:"files_touched"`

	// Agent identifies the agent that created this checkpoint (e.g., "Claude Code", "Cursor")
	Agent types.AgentType `json:"agent,omitempty"`

	// Model is the LLM model used during the session (e.g., "claude-sonnet-4-20250514").
	// Always written to metadata (empty string when unknown) so consumers can rely on the field's presence.
	Model string `json:"model"`

	// TurnID correlates checkpoints from the same agent turn.
	// When a turn's work spans multiple commits, each gets its own checkpoint
	// but they share the same TurnID for future aggregation/deduplication.
	TurnID string `json:"turn_id,omitempty"`

	// Task checkpoint fields (only populated for task checkpoints)
	IsTask    bool   `json:"is_task,omitempty"`
	ToolUseID string `json:"tool_use_id,omitempty"`

	// Transcript position at checkpoint start - tracks what was added during this checkpoint
	TranscriptIdentifierAtStart string `json:"transcript_identifier_at_start,omitempty"` // Last identifier when checkpoint started (UUID for Claude, message ID for Gemini)
	CheckpointTranscriptStart   int    `json:"checkpoint_transcript_start,omitempty"`    // Transcript line offset at start of this checkpoint's data

	// Deprecated: Use CheckpointTranscriptStart instead. Written for backward compatibility with older CLI versions.
	TranscriptLinesAtStart int `json:"transcript_lines_at_start,omitempty"`

	// Token usage for this checkpoint
	TokenUsage *types.TokenUsage `json:"token_usage,omitempty"`

	// SkillEvents records explicit native skill signals observed in this session.
	// Consumers use these anchors to collapse skill-related raw transcript events.
	SkillEventsVersion int                `json:"skill_events_version,omitempty"`
	SkillEvents        []types.SkillEvent `json:"skill_events,omitempty"`

	// SessionMetrics contains hook-provided session metrics (duration, turns, context usage).
	// Populated for agents that provide these metrics via hooks (e.g., Cursor).
	SessionMetrics *SessionMetrics `json:"session_metrics,omitempty"`

	// AI-generated summary of the checkpoint
	Summary *Summary `json:"summary,omitempty"`

	// Attribution is line-level attribution calculated at commit time
	Attribution *Attribution `json:"initial_attribution,omitempty"`

	// PromptAttributions is the raw per-prompt attribution data used to compute Attribution.
	// Diagnostic field — shows which prompt recorded which "user" lines.
	PromptAttributions json.RawMessage `json:"prompt_attributions,omitempty"`

	// Kind identifies the session purpose (e.g., "agent_review"). Empty for normal sessions.
	Kind string `json:"kind,omitempty"`

	// ReviewSkills lists the review skills that were run (only set when Kind is a review kind).
	// May be empty when a review was attached post-hoc without declared skills.
	ReviewSkills []string `json:"review_skills,omitempty"`

	// ReviewPrompt is the actual text of the review request (composed prompt
	// for spawn, first user prompt for attach). Only set when Kind is a
	// review kind.
	ReviewPrompt string `json:"review_prompt,omitempty"`

	// InvestigateRunID is the 12-hex-char ID of the parent investigation
	// run. Only set when Kind is an investigate kind.
	InvestigateRunID string `json:"investigate_run_id,omitempty"`

	// InvestigateTopic is the human-readable topic the investigation was
	// asked to investigate. Only set when Kind is an investigate kind.
	InvestigateTopic string `json:"investigate_topic,omitempty"`
}

type PersistentStore interface {
	CheckpointReader
	SessionReader
	Writer
}

type PrecomputedTranscriptBlobs struct {
	// ChunkHashes are the blob hashes for each transcript chunk, in order.
	// Always non-empty when built via PrecomputeTranscriptBlobs (a non-empty
	// transcript chunks to at least one entry; callers should skip precompute
	// for empty transcripts).
	ChunkHashes []plumbing.Hash

	// ContentHashBlob is the blob hash of the "sha256:<hex>" content-hash
	// string for the transcript.
	ContentHashBlob plumbing.Hash

	// ContentHash is the "sha256:<hex>" string itself, so the short-circuit
	// path can compare without re-reading the blob.
	ContentHash string
}

type Session WriteOptions

type SessionContent struct {
	// Metadata contains the session-specific metadata
	Metadata Metadata

	// Transcript is the session transcript content
	Transcript []byte

	// TranscriptBlobHashes are the stored raw transcript blob hashes in chunk
	// order. Callers that rewrite the same transcript under a different path can
	// reuse these content-addressed blobs instead of storing duplicate blobs.
	TranscriptBlobHashes []plumbing.Hash

	// Prompts contains user prompts from this session
	Prompts string
}

type SessionFilePaths struct {
	Metadata string `json:"metadata"`
	// Transcript points at the raw full.jsonl, which CLI read paths
	// (rewind/resume/explain) resolve by filename.
	Transcript string `json:"transcript,omitempty"`
	// CompactTranscript points at the compact transcript.jsonl when one was
	// generated alongside full.jsonl. Omitted otherwise (non-compactable,
	// empty, or oversized transcripts, and older CLI versions).
	CompactTranscript string `json:"compact_transcript,omitempty"`
	ContentHash       string `json:"content_hash,omitempty"`
	Prompt            string `json:"prompt"`
}

type SessionMetrics struct {
	DurationMs        int64 `json:"duration_ms,omitempty"`
	TurnCount         int   `json:"turn_count,omitempty"`
	ContextTokens     int   `json:"context_tokens,omitempty"`
	ContextWindowSize int   `json:"context_window_size,omitempty"`
}

type SessionReader interface {
	ReadSessionContent(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*SessionContent, error)
	ReadSessionMetadata(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*Metadata, error)
	ReadSessionPrompts(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (string, error)
	ReadSessionMetadataAndPrompts(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*Metadata, string, error)
}

type SessionSummary struct {
	CheckpointID id.CheckpointID
	Summary      *Summary
}

type SessionTranscript UpdateOptions

type Summary struct {
	Intent    string           `json:"intent"`     // What user wanted to accomplish
	Outcome   string           `json:"outcome"`    // What was achieved
	Learnings LearningsSummary `json:"learnings"`  // Categorized learnings
	Friction  []string         `json:"friction"`   // Problems/annoyances encountered
	OpenItems []string         `json:"open_items"` // Tech debt, unfinished work
}

type UpdateOptions struct {
	// CheckpointID identifies the checkpoint to update
	CheckpointID id.CheckpointID

	// SessionID identifies which session slot to update within the checkpoint
	SessionID string

	// Transcript is the full session transcript (replaces existing).
	// Must be pre-redacted (via redact.JSONLBytes or redact.AlreadyRedacted for trusted sources).
	Transcript redact.RedactedBytes

	// Prompts contains the raw user prompts (replaces existing).
	// See WriteOptions.Prompts.
	Prompts []string

	// Agent identifies the agent type (needed for transcript chunking)
	Agent types.AgentType

	// SkillEvents replaces the session metadata skill_events when non-empty.
	SkillEvents []types.SkillEvent

	// PrecomputedBlobs, if non-nil, provides chunk blob hashes and the
	// content-hash blob hash computed once for this transcript. When set,
	// transcript backfill skips the per-call ChunkTranscript + zlib work and
	// reuses these hashes. Used by finalizeAllTurnCheckpoints to avoid
	// re-compressing identical content N times.
	PrecomputedBlobs *PrecomputedTranscriptBlobs
}

type WriteOptions struct {
	// CheckpointID is the stable 12-hex-char identifier
	CheckpointID id.CheckpointID

	// SessionID is the session identifier
	SessionID string

	// CreatedAt is when the checkpoint was originally created.
	// When zero, writers use the current time.
	CreatedAt time.Time

	// Strategy is the name of the strategy that created this checkpoint
	Strategy string

	// Branch is the branch name where the checkpoint was created (empty if detached HEAD)
	Branch string

	// Transcript is the session transcript content (full.jsonl).
	// Must be pre-redacted (via redact.JSONLBytes or redact.AlreadyRedacted for trusted sources).
	Transcript redact.RedactedBytes

	// Prompts contains the raw user prompts from the session. Run through
	// redactedJoinedPrompts before persisting — the writer does this
	// inside writeSessionToSubdirectory.
	Prompts []string

	// FilesTouched are files modified during the session
	FilesTouched []string

	// CheckpointsCount is the displayed "steps" count for this session: the number
	// of user prompts attributed to this checkpoint (floored at 1). Despite the
	// historical name/JSON tag, it is no longer a count of checkpoints.
	CheckpointsCount int

	// SaveStepCount is the number of SaveStep-recorded steps (shadow-branch
	// commits) for this session. Distinct from CheckpointsCount (the displayed
	// prompt count): this is the honest "did real checkpoint work happen" signal
	// used to gate combined attribution. 0 means a commit-only / fallback session.
	SaveStepCount int

	// EphemeralBranch is the shadow branch name (for manual-commit strategy)
	EphemeralBranch string

	// AuthorName is the name to use for commits
	AuthorName string

	// AuthorEmail is the email to use for commits
	AuthorEmail string

	// MetadataDir is a directory containing additional metadata files to copy
	// If set, all files in this directory will be copied to the checkpoint path
	// This is useful for copying task metadata files, subagent transcripts, etc.
	MetadataDir string

	// Task checkpoint fields (for task/subagent checkpoints)
	IsTask    bool   // Whether this is a task checkpoint
	ToolUseID string // Tool use ID for task checkpoints

	// Additional task checkpoint fields for subagent checkpoints
	AgentID                string // Subagent identifier
	CheckpointUUID         string // UUID for transcript truncation when rewinding
	TranscriptPath         string // Path to session transcript file (alternative to in-memory Transcript)
	SubagentTranscriptPath string // Path to subagent's transcript file

	// Incremental checkpoint fields
	IsIncremental       bool   // Whether this is an incremental checkpoint
	IncrementalSequence int    // Checkpoint sequence number
	IncrementalType     string // Tool type that triggered this checkpoint
	IncrementalData     []byte // Tool input payload for this checkpoint

	// Commit message fields (used for task checkpoints)
	CommitSubject string // Subject line for the metadata commit (overrides default)

	// Agent identifies the agent that created this checkpoint (e.g., "Claude Code", "Cursor")
	Agent types.AgentType

	// Model is the LLM model used during the session (e.g., "claude-sonnet-4-20250514")
	Model string

	// TurnID correlates checkpoints from the same agent turn.
	TurnID string

	// Transcript position at checkpoint start - tracks what was added during this checkpoint
	TranscriptIdentifierAtStart string // Last identifier when checkpoint started (UUID for Claude, message ID for Gemini)
	CheckpointTranscriptStart   int    // Transcript line offset at start of this checkpoint's data

	// TokenUsage contains the token usage for this checkpoint
	TokenUsage *types.TokenUsage

	// SkillEvents records explicit native skill signals observed in this session.
	SkillEvents []types.SkillEvent

	// SessionMetrics contains hook-provided session metrics (duration, turns, context usage)
	SessionMetrics *SessionMetrics

	// Attribution is line-level attribution calculated at commit time
	// comparing checkpoint tree (agent work) to committed tree (may include human edits)
	Attribution *Attribution

	// PromptAttributionsJSON is the raw PromptAttributions data, JSON-encoded.
	// Persisted for diagnostic purposes — shows exactly which prompt recorded
	// which "user" lines, enabling root cause analysis of attribution bugs.
	// Uses json.RawMessage to avoid importing session package.
	PromptAttributionsJSON json.RawMessage

	// CombinedAttribution is holistic attribution across all sessions.
	// Used during migration to preserve v1 root summary attribution.
	// During normal condensation this is nil (computed post-commit via a CheckpointAttribution write).
	CombinedAttribution *Attribution

	// Summary is an optional AI-generated summary for this checkpoint.
	// This field may be nil when:
	//   - summarization is disabled in settings
	//   - summary generation failed (non-blocking, logged as warning)
	//   - the transcript was empty or too short to summarize
	//   - the checkpoint predates the summarization feature
	Summary *Summary

	// Kind identifies the session purpose (e.g., "agent_review"). Empty for normal sessions.
	Kind string

	// ReviewSkills is the snapshot of skills used (only meaningful when Kind is a review kind).
	// May be empty when a review is attached post-hoc without declared skills.
	ReviewSkills []string

	// ReviewPrompt is the actual text of the review request (composed prompt
	// for spawn, first user prompt for attach). Only meaningful when Kind is
	// a review kind.
	ReviewPrompt string

	// HasReview is set by the caller when this session should mark its
	// checkpoint as reviewed. The caller computes this (e.g. via
	// session.Kind.IsReview) because checkpoint can't import session
	// — the session package imports checkpoint, creating a cycle.
	HasReview bool

	// InvestigateRunID is the 12-hex-char ID of the parent investigation
	// run (only meaningful when Kind is an investigate kind).
	InvestigateRunID string

	// InvestigateTopic is the human-readable topic the investigation was
	// asked to investigate (only meaningful when Kind is an investigate
	// kind).
	InvestigateTopic string

	// HasInvestigation is set by the caller when this session should mark
	// its checkpoint as part of an investigation. The caller computes this
	// (e.g. via session.Kind.IsInvestigate) because checkpoint can't import
	// session — the session package imports checkpoint, creating a cycle.
	HasInvestigation bool
}

type WriteRequest interface {
	// contains filtered or unexported methods
}

type Writer interface {
	Write(ctx context.Context, req WriteRequest) error
}