checkpoint: define split store interfaces

7b88390→main·

pfleidi·4w ago·3 files·+33 added/-50 removed

Replace the combined checkpoint Store interface with committed, temporary, and optional author capabilities.

This keeps the current GitStore implementation while making the committed storage surface independent from shadow-branch operations.

Sessions

b6e36ed89559View transcript

Changes

3

• cmd/entire/cli/checkpoint

• Mcheckpoint.go+8/-48

• Mcommitted_reader_resolve.go+20

• Mstore.go+5/-2

59 unmodified lines

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
63
64
65
76
77
78
79
80
81
82
83
66
67
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
68
69
70
71
72
73
74
75

59 unmodified lines

Committed
// Store provides low-level primitives for reading and writing checkpoints.
// This is used by strategies to implement their storage approach.
//
// The interface matches the GitStore implementation signatures directly:
// - WriteTemporary takes WriteTemporaryOptions and returns a result with commit hash and skip status
// - ReadTemporary takes baseCommit (not sessionID) since shadow branches are keyed by commit
// - List methods return implementation-specific info types for richer data

type Store interface {
    // WriteTemporary writes a temporary checkpoint (full state) to a shadow branch.
    // Shadow branches are named entire/<base-commit-short-hash>.
    // Returns a result containing the commit hash and whether the checkpoint was skipped.
    // Checkpoints are skipped (deduplicated) when the tree hash matches the previous checkpoint.
    // TemporaryStore provides the production shadow-branch checkpoint surface.
    type TemporaryStore interface {
        WriteTemporary(ctx context.Context, opts WriteTemporaryOptions) (WriteTemporaryResult, error)

// ReadTemporary reads the latest checkpoint from a shadow branch.
        // baseCommit is the commit hash the session is based on.
        // worktreeID is the internal git worktree identifier (empty for main worktree).
        // Returns nil, nil if the shadow branch doesn't exist.
        ReadTemporary(ctx context.Context, baseCommit, worktreeID string) (*ReadTemporaryResult, error)

// ListTemporary lists all shadow branches with their checkpoint info.
        WriteTemporaryTask(ctx context.Context, opts WriteTemporaryTaskOptions) (plumbing.Hash, error)
        ListTemporary(ctx context.Context) ([]TemporaryInfo, error)

// WriteCommitted writes a committed checkpoint to the entire/checkpoints/v1 branch.
        // Checkpoints are stored at sharded paths: <id[:2]>/<id[2:]>/
        WriteCommitted(ctx context.Context, opts WriteCommittedOptions) error

// ReadCommitted reads a committed checkpoint's summary by ID.
        // Returns only the CheckpointSummary (paths + aggregated stats), not actual content.
        // Use ReadSessionContent to read actual transcript/prompts.
        // Returns nil, nil if the checkpoint does not exist.
        ReadCommitted(ctx context.Context, checkpointID id.CheckpointID) (*CheckpointSummary, error)

// ReadSessionContent reads the actual content for a specific session within a checkpoint.
        // sessionIndex is 0-based (0 for first session, 1 for second, etc.).
        // Returns the session's metadata, transcript, and prompts.
        ReadSessionContent(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*SessionContent, error)

// ReadSessionContentByID reads a session's content by its session ID.
        // Useful when you have the session ID but don't know its index within the checkpoint.
        ReadSessionContentByID(ctx context.Context, checkpointID id.CheckpointID, sessionID string) (*SessionContent, error)

// ListCommitted lists all committed checkpoints.
        ListCommitted(ctx context.Context) ([]CommittedInfo, error)

// UpdateCommitted replaces the transcript and prompts for an existing
        // committed checkpoint. Used at stop time to finalize checkpoints with the full
        // session transcript (prompt to stop event).
        // Returns ErrCheckpointNotFound if the checkpoint doesn't exist.
        UpdateCommitted(ctx context.Context, opts UpdateCommittedOptions) error
        ListTemporaryCheckpoints(ctx context.Context, baseCommit, worktreeID, sessionID string, limit int) ([]TemporaryCheckpointInfo, error)
        ListCheckpointsForBranch(ctx context.Context, branchName, sessionID string, limit int) ([]TemporaryCheckpointInfo, error)
        ListAllTemporaryCheckpoints(ctx context.Context, sessionID string, limit int) ([]TemporaryCheckpointInfo, error)
        GetTranscriptFromCommit(ctx context.Context, commitHash plumbing.Hash, metadataDir string, agentType types.AgentType) ([]byte, error)
        ShadowBranchExists(baseCommit, worktreeID string) bool
}

// WriteTemporaryResult contains the result of writing a temporary checkpoint.

Mcmd/entire/cli/checkpoint/checkpoint.go+8/-48

20 unmodified lines

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

20 unmodified lines

ReadSessionPrompts(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (string, error)
}

// CommittedWriter provides write access to committed checkpoint data.
type CommittedWriter interface {
    WriteCommitted(ctx context.Context, opts WriteCommittedOptions) error
    UpdateCommitted(ctx context.Context, opts UpdateCommittedOptions) error
    UpdateSummary(ctx context.Context, checkpointID id.CheckpointID, summary *Summary) error
    UpdateCheckpointSummary(ctx context.Context, checkpointID id.CheckpointID, combinedAttribution *InitialAttribution) error
}

// CommittedStore provides the production committed checkpoint storage surface.
type CommittedStore interface {
    CommittedListReader
    ReadSessionMetadataAndPrompts(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*SessionContent, error)
    CommittedWriter
}

// AuthorReader provides optional checkpoint author lookup.
type AuthorReader interface {
    GetCheckpointAuthor(ctx context.Context, checkpointID id.CheckpointID) (Author, error)
}

// ReadCommittedCheckpoint reads a committed checkpoint summary and normalizes
// a nil store response into ErrCheckpointNotFound.
func ReadCommittedCheckpoint(ctx context.Context, reader CommittedReader, checkpointID id.CheckpointID) (*CheckpointSummary, error) {
}

Mcmd/entire/cli/checkpoint/committed_reader_resolve.go+20

6 unmodified lines

7 8 9 10 11 10 11 12 13 14 15 16 17

6 unmodified lines

"github.com/go-git/go-git/v6/plumbing"

// Compile-time check that GitStore implements the Store interface. var _ Store = (*GitStore)(nil) var ( _ CommittedStore = (*GitStore)(nil) _ TemporaryStore = (*GitStore)(nil) _ AuthorReader = (*GitStore)(nil) )

// GitStore provides operations for both temporary and committed checkpoint // storage. Writes target refs.Primary; committed reads resolve against

Mcmd/entire/cli/checkpoint/store.go+5/-2