entirecheckpoint

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 13, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package entirecheckpoint reads one Entire checkpoint tree without assigning session-model meaning to its records.

Index

Constants

View Source 
const TrailerKey = "Entire-Checkpoint"

TrailerKey is the commit trailer Entire writes to name the checkpoint that recorded the commit's sessions.

Variables

View Source 
var (
	ErrCompactVersion    = errors.New("unsupported Entire compact transcript version")
	ErrCompactRecordType = errors.New("unknown Entire compact record type")
	ErrCompactBlockShape = errors.New("unknown Entire compact block shape")
)
View Source 
var ErrEscapingSessionRef = errors.New("Entire session ref escapes checkpoint root")

Functions

func CanonicalID 

func CanonicalID(s string) (string, bool)

CanonicalID reports whether s is an Entire checkpoint id and returns its canonical spelling. Entire writes two formats: a legacy 12-character hex id, always lower-case, and a 26-character Crockford base32 ULID, always upper-case. Either is accepted in any case and returned in the case Entire writes it, so the same checkpoint is one key wherever it is stored.

A ULID is validated as Entire validates it: the Crockford alphabet without the aliases I, L, O and U, which Entire never emits, and a first character of at most 7, since a larger one overflows the 48-bit timestamp.

func ContentHashOf 

func ContentHashOf(data []byte) string

ContentHashOf is content_hash.txt's spelling of data's hash.

func MessageTrailers 

func MessageTrailers(message string) []string

MessageTrailers returns, as "Entire-Checkpoint: <value>" lines in message order for ParseTrailers, every Entire-Checkpoint value a commit message names. It is the union of two readings:

  • Every id Entire's own pattern finds that CanonicalID accepts, which is what Entire links the commit to. The pattern is not anchored to a line, so an id after the key in the middle of a line counts, as it does for Entire.
  • Every line shaped like the trailer (the key at the start of the line, in any case, then optional blanks and a colon), as git's trailer block would hold it, wherever the line sits. This keeps what ParseTrailers accepts beyond Entire's pattern (a key or an id in another case) and reports a malformed value. A line on which Entire's pattern found a valid id is that id and nothing more, so text after the id is not reported as malformed.

A value the key introduces in the middle of a line that is not an id is prose about the trailer, not a malformed trailer, and is ignored.

func ParseMessage 

func ParseMessage(message string) (ids, malformed []string)

ParseMessage reads every Entire-Checkpoint a commit message names, wherever in the message it sits, and returns what ParseTrailers returns for them. This is how a commit is read for its checkpoints, not from git's trailer block alone: a GitHub squash merge copies each squashed commit's message, trailers included, into its body, so the checkpoints of all but the last squashed commit sit in body paragraphs the trailer block does not include.

func ParseTrailers 

func ParseTrailers(trailers []string) (ids, malformed []string)

ParseTrailers reads a commit's Entire-Checkpoint trailers, given as "Key: value" lines. The key is matched without regard to case. ids holds every valid checkpoint id in canonical form, in trailer order, each once, as Entire's own ParseAllCheckpoints returns them. malformed holds every other value, trimmed, in trailer order, each once, so a caller can report what it skipped. Both are empty when the commit names no checkpoint at all.

Types

type Attribution 

type Attribution struct {
	CalculatedAt      string  `json:"calculated_at"`
	AgentLines        int64   `json:"agent_lines"`
	AgentRemoved      int64   `json:"agent_removed"`
	HumanAdded        int64   `json:"human_added"`
	HumanModified     int64   `json:"human_modified"`
	HumanRemoved      int64   `json:"human_removed"`
	TotalCommitted    int64   `json:"total_committed"`
	TotalLinesChanged int64   `json:"total_lines_changed"`
	AgentPercentage   float64 `json:"agent_percentage"`
	MetricVersion     int     `json:"metric_version"`
}

type Checkpoint 

type Checkpoint struct {
	Metadata CheckpointMetadata `json:"metadata"`
	Sessions []*SessionSnapshot `json:"sessions"`
	// Tasks are the subagents kept at the checkpoint root, shared by every
	// session in it (tasks.go).
	Tasks []*Task `json:"tasks,omitempty"`
}

func ParseCheckpoint 

func ParseCheckpoint(fsys fs.FS) (*Checkpoint, error)

ParseCheckpoint reads one checkpoint directory from fsys. The filesystem root is the checkpoint directory itself, matching tar exports and the hosted resolver's checkpoint filesystem.

func ParseCheckpointWith 

func ParseCheckpointWith(fsys fs.FS, profile traceprocessing.MappingProfile) (*Checkpoint, error)

ParseCheckpointWith retains the hosted resource and duplicate-source checks, task discovery and Pi compact interpretation, while local defaults stay intact.

func ParseHostedCheckpoint 

func ParseHostedCheckpoint(fsys fs.FS) (*Checkpoint, error)

type CheckpointMetadata 

type CheckpointMetadata struct {
	CLIVersion          string        `json:"cli_version"`
	CheckpointID        string        `json:"checkpoint_id"`
	Strategy            string        `json:"strategy"`
	Branch              string        `json:"branch"`
	CheckpointsCount    int           `json:"checkpoints_count"`
	FilesTouched        []string      `json:"files_touched"`
	Sessions            []SessionRefs `json:"sessions"`
	TokenUsage          *TokenUsage   `json:"token_usage"`
	CombinedAttribution *Attribution  `json:"combined_attribution"`
	CommitSHA           string        `json:"commit_sha"`
	HasReview           *bool         `json:"has_review"`
	HasInvestigation    *bool         `json:"has_investigation"`
	Imported            *bool         `json:"imported"`

	Raw         json.RawMessage `json:"-"`
	Keys        []string        `json:"-"`
	UnknownKeys []string        `json:"-"`
}

CheckpointMetadata is the checkpoint-level metadata.json record. Entire has added fields over time, so fields are optional and unknown top-level keys are retained for drift reporting.

type CompactBlock 

type CompactBlock struct {
	Index   int                  `json:"index"`
	Kind    CompactBlockKind     `json:"kind"`
	ID      string               `json:"id,omitempty"`
	Text    string               `json:"text,omitempty"`
	Image   *CompactImageBlock   `json:"image,omitempty"`
	ToolUse *CompactToolUseBlock `json:"tool_use,omitempty"`
	Raw     json.RawMessage      `json:"raw"`
}

type CompactBlockKind 

type CompactBlockKind string
const (
	CompactUserText      CompactBlockKind = "user_text"
	CompactImage         CompactBlockKind = "image"
	CompactAssistantText CompactBlockKind = "assistant_text"
	CompactToolUse       CompactBlockKind = "tool_use"
)

type CompactImageBlock 

type CompactImageBlock struct {
	Source CompactImageSource `json:"source"`
}

type CompactImageSource 

type CompactImageSource struct {
	Type      string `json:"type"`
	MediaType string `json:"media_type"`
	Data      string `json:"data"`
}

type CompactRecord 

type CompactRecord struct {
	Ordinal      int               `json:"ordinal"`
	Version      int               `json:"v"`
	Agent        string            `json:"agent"`
	CLIVersion   string            `json:"cli_version"`
	Type         CompactRecordType `json:"type"`
	Timestamp    *time.Time        `json:"ts,omitempty"`
	ID           string            `json:"id,omitempty"`
	InputTokens  int64             `json:"input_tokens,omitempty"`
	OutputTokens int64             `json:"output_tokens,omitempty"`
	Content      []CompactBlock    `json:"content"`
	Raw          json.RawMessage   `json:"raw"`
}

func DecodeCompact 

func DecodeCompact(r io.Reader) ([]CompactRecord, error)

DecodeCompact reads Entire compact transcript v1. Unlike live native transcript readers, a truncated final record is an error: checkpoint blobs are immutable and must be complete.

func DecodeCompactWith 

func DecodeCompactWith(r io.Reader, profile traceprocessing.MappingProfile) ([]CompactRecord, error)

func DecodeHostedCompact 

func DecodeHostedCompact(r io.Reader) ([]CompactRecord, error)

type CompactRecordType 

type CompactRecordType string
const (
	CompactUser      CompactRecordType = "user"
	CompactAssistant CompactRecordType = "assistant"
)

type CompactResultFile 

type CompactResultFile struct {
	FilePath string `json:"filePath"`
	NumLines *int   `json:"numLines,omitempty"`
}

type CompactToolResult 

type CompactToolResult struct {
	Output string             `json:"output"`
	Status string             `json:"status"`
	File   *CompactResultFile `json:"file,omitempty"`
	Raw    json.RawMessage    `json:"raw"`
}

type CompactToolUseBlock 

type CompactToolUseBlock struct {
	ID           string             `json:"id"`
	Name         string             `json:"name"`
	Input        json.RawMessage    `json:"input"`
	InputPresent bool               `json:"input_present"`
	Result       *CompactToolResult `json:"result,omitempty"`
}

type HashVerification 

type HashVerification struct {
	Recorded string `json:"recorded,omitempty"`
	Actual   string `json:"actual,omitempty"`
	Checked  bool   `json:"checked"`
	Mismatch bool   `json:"mismatch"`
}

HashVerification records whether full.jsonl matches content_hash.txt. Mismatch is data for the mapper to surface as a warning, not a parse error.

func VerifyContentHash 

func VerifyContentHash(full []byte, fullPresent bool, recorded string) HashVerification

type PromptAttribution 

type PromptAttribution struct {
	CheckpointNumber   int              `json:"checkpoint_number"`
	UserLinesAdded     int64            `json:"user_lines_added"`
	UserLinesRemoved   int64            `json:"user_lines_removed"`
	AgentLinesAdded    int64            `json:"agent_lines_added"`
	AgentLinesRemoved  int64            `json:"agent_lines_removed"`
	UserAddedPerFile   map[string]int64 `json:"user_added_per_file"`
	UserRemovedPerFile map[string]int64 `json:"user_removed_per_file"`
}

type SessionList 

type SessionList []SessionRefs

SessionList is the checkpoint's sessions array. Decoding stops with an error at entry maxSessions+1, so an oversized array of tiny entries is rejected before each one is expanded into a SessionRefs.

func (*SessionList) UnmarshalJSON 

func (l *SessionList) UnmarshalJSON(raw []byte) error

type SessionMetadata 

type SessionMetadata struct {
	CLIVersion                  string              `json:"cli_version"`
	CheckpointID                string              `json:"checkpoint_id"`
	SessionID                   string              `json:"session_id"`
	Strategy                    string              `json:"strategy"`
	CreatedAt                   string              `json:"created_at"`
	Branch                      string              `json:"branch"`
	CheckpointsCount            int                 `json:"checkpoints_count"`
	SaveStepCount               *int                `json:"save_step_count"`
	FilesTouched                []string            `json:"files_touched"`
	Agent                       string              `json:"agent"`
	Model                       string              `json:"model"`
	TurnID                      string              `json:"turn_id"`
	CompactTranscriptStart      *int                `json:"compact_transcript_start"`
	CheckpointTranscriptStart   *int                `json:"checkpoint_transcript_start"`
	TranscriptLinesAtStart      *int                `json:"transcript_lines_at_start"`
	TranscriptIdentifierAtStart json.RawMessage     `json:"transcript_identifier_at_start"`
	TokenUsage                  *TokenUsage         `json:"token_usage"`
	SessionMetrics              *SessionMetrics     `json:"session_metrics"`
	InitialAttribution          *Attribution        `json:"initial_attribution"`
	PromptAttributions          []PromptAttribution `json:"prompt_attributions"`
	SkillEventsVersion          *int                `json:"skill_events_version"`
	SkillEvents                 []SkillEvent        `json:"skill_events"`
	IsTask                      *bool               `json:"is_task"`
	ToolUseID                   string              `json:"tool_use_id"`
	Kind                        string              `json:"kind"`
	Summary                     json.RawMessage     `json:"summary"`
	ReviewSkills                []string            `json:"review_skills"`
	ReviewPrompt                string              `json:"review_prompt"`
	InvestigateRunID            string              `json:"investigate_run_id"`
	InvestigateTopic            string              `json:"investigate_topic"`
	CommitSHA                   string              `json:"commit_sha"`
	Imported                    *bool               `json:"imported"`

	Raw         json.RawMessage `json:"-"`
	Keys        []string        `json:"-"`
	UnknownKeys []string        `json:"-"`
}

SessionMetadata is one wrapped session's metadata.json record.

type SessionMetrics 

type SessionMetrics struct {
	TurnCount         int64 `json:"turn_count"`
	DurationMS        int64 `json:"duration_ms"`
	ContextTokens     int64 `json:"context_tokens"`
	ContextWindowSize int64 `json:"context_window_size"`
}

type SessionRefs 

type SessionRefs struct {
	Metadata          string `json:"metadata"`
	Transcript        string `json:"transcript"`
	CompactTranscript string `json:"compact_transcript"`
	ContentHash       string `json:"content_hash"`
	Prompt            string `json:"prompt"`
	AssetsManifest    string `json:"assets_manifest"`
}

SessionRefs names the files for one wrapped session. Values are branch-root relative in stored checkpoints, although ParseCheckpoint also accepts the positional layout directly.

type SessionSnapshot 

type SessionSnapshot struct {
	Index          int              `json:"index"`
	Directory      string           `json:"directory"`
	Refs           SessionRefs      `json:"refs"`
	Metadata       SessionMetadata  `json:"metadata"`
	Full           []byte           `json:"full,omitempty"`
	FullPresent    bool             `json:"full_present"`
	CompactRaw     []byte           `json:"compact_raw,omitempty"`
	CompactPresent bool             `json:"compact_present"`
	Compact        []CompactRecord  `json:"compact,omitempty"`
	Prompt         []byte           `json:"prompt,omitempty"`
	PromptPresent  bool             `json:"prompt_present"`
	AssetsManifest []byte           `json:"assets_manifest,omitempty"`
	AssetsPresent  bool             `json:"assets_present"`
	ContentHash    string           `json:"content_hash,omitempty"`
	Hash           HashVerification `json:"hash"`
}

type Shape 

type Shape struct {
	CLIVersions           traceprocessing.Versions `json:"cli_versions"`
	CheckpointKeys        map[string]int           `json:"checkpoint_keys"`
	SessionKeys           map[string]int           `json:"session_keys"`
	UnknownCheckpointKeys map[string]int           `json:"unknown_checkpoint_keys,omitempty"`
	UnknownSessionKeys    map[string]int           `json:"unknown_session_keys,omitempty"`
	CompactRecordTypes    map[string]int           `json:"compact_record_types"`
	CompactBlockKinds     map[string]int           `json:"compact_block_kinds"`
	CompactAgents         map[string]int           `json:"compact_agents"`
	HashChecked           int                      `json:"hash_checked"`
	HashMismatches        int                      `json:"hash_mismatches"`
}

func Survey 

func Survey(checkpoints []*Checkpoint) Shape

type Skill 

type Skill struct {
	Name string `json:"name"`
}

type SkillCollapse 

type SkillCollapse struct {
	Target           string `json:"target"`
	Label            string `json:"label"`
	DefaultCollapsed bool   `json:"default_collapsed"`
}

type SkillEvent 

type SkillEvent struct {
	ID               string            `json:"id"`
	EventType        string            `json:"event_type"`
	Skill            Skill             `json:"skill"`
	Source           SkillSource       `json:"source"`
	TurnID           string            `json:"turn_id"`
	TranscriptAnchor *TranscriptAnchor `json:"transcript_anchor"`
	Timestamp        string            `json:"timestamp"`
	Native           SkillNative       `json:"native"`
	Collapse         SkillCollapse     `json:"collapse"`
}

type SkillNative 

type SkillNative struct {
	ToolName  string `json:"tool_name"`
	ToolUseID string `json:"tool_use_id"`
}

type SkillSource 

type SkillSource struct {
	Agent      string `json:"agent"`
	Signal     string `json:"signal"`
	Confidence string `json:"confidence"`
}

type Task 

type Task struct {
	Directory string `json:"directory"`
	// Meta is task.json. MetaPresent is false when the directory has none.
	Meta        TaskMeta `json:"meta"`
	MetaPresent bool     `json:"meta_present"`
	// Transcript is the single agent-<id>.jsonl, the subagent's own native
	// transcript, and TranscriptName its file name.
	Transcript        []byte `json:"-"`
	TranscriptName    string `json:"transcript_name,omitempty"`
	TranscriptPresent bool   `json:"transcript_present"`
	Problem           string `json:"problem,omitempty"`
}

Task is one `tasks/<id>/` directory at the checkpoint root: what Entire kept of a subagent the checkpoint's sessions ran. The directory name is the spawning tool call (Claude Code) or the child thread (Codex). The checkpoint metadata does not list tasks, and nothing in a task names the session that spawned it except the transcript's own lines.

A task that cannot be read is kept with Problem set rather than failing the checkpoint: one damaged subagent must not cost the sessions their transcripts.

func (*Task) AgentID 

func (t *Task) AgentID() string

AgentID is the subagent id the transcript file is named after, falling back to task.json.

type TaskMeta 

type TaskMeta struct {
	ToolUseID       string          `json:"tool_use_id"`
	AgentID         string          `json:"agent_id"`
	SubagentType    string          `json:"subagent_type"`
	TaskDescription string          `json:"task_description"`
	StartedAt       string          `json:"started_at"`
	CompletedAt     string          `json:"completed_at"`
	TokenUsage      json.RawMessage `json:"token_usage,omitempty"`
}

TaskMeta is task.json. Entire writes it for every task, with or without a transcript.

type TokenUsage 

type TokenUsage struct {
	InputTokens         int64 `json:"input_tokens"`
	CacheCreationTokens int64 `json:"cache_creation_tokens"`
	CacheReadTokens     int64 `json:"cache_read_tokens"`
	OutputTokens        int64 `json:"output_tokens"`
	APICallCount        int64 `json:"api_call_count"`
}

func (TokenUsage) Negative 

func (u TokenUsage) Negative() bool

Negative reports whether any count is below zero. The Entire CLI derives Codex usage as a difference of cumulative counters, and a resumed Codex session restarts those counters, so a checkpoint can record a negative delta that no session ever consumed.

type TranscriptAnchor 

type TranscriptAnchor struct {
	Unit      string   `json:"unit"`
	Start     int      `json:"start"`
	End       int      `json:"end"`
	EntryIDs  []string `json:"entry_ids"`
	ToolUseID string   `json:"tool_use_id"`
}

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.