checkpoint: address Copilot review on the api/checkpoint facade

3e0e779·

Soph·4w ago·3 files·+35 added/-22 removed

- Re-export the contract helper functions as thin wrapper funcs instead of exported vars, so the facade symbols can't be reassigned by consumers. - Tighten the package doc: the contract avoids the heavy agent runtime/TUI and git-implementation packages, but does depend on leaf value packages (agent/types, checkpoint/id) and go-git plumbing — don't imply zero agent dep. - Reword moved DTO comments that named private CLI internals (redactedJoinedPrompts/writeSessionToSubdirectory/ChunkTranscript/...) to describe behavior, since this is backend-facing contract documentation.

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com

Sessions

907bd3ab830aView transcript

?\ can you run simplify on each PR?Claude Code·Opus 4.8[1m]·1 step

Changes

3

• api/checkpoint

- Mdoc.go+3/-1

- Mmetadata.go+12/-14

• cmd/entire/cli/checkpoint

- Maliases.go+20/-7

3 unmodified lines

4
5
6
7
7
8
9
10
11
12

3 unmodified lines

// It is the pluggable surface from issue #1433: a storage backend implements
// these interfaces and operates on these types without depending on the CLI's
// agent, TUI, or git-implementation packages. The git-backed implementation
// heavy agent runtime, TUI, or git-implementation packages. (It depends only
// on leaf value packages — agent/types, checkpoint/id — and go-git plumbing.)
// The git-backed implementation
// (GitStore, Open, the shadow-branch/temporary machinery) lives in the
// cmd/entire/cli/checkpoint package, which imports this one and re-exports
// these types as aliases so existing CLI call sites are unaffected.

Mapi/checkpoint/doc.go+3/-1

32 unmodified lines

33
34
35
36
37
38
36
37
38
39
40
151 unmodified lines

192
193
194
196
197
198
199
195
196
197
198
199
200
201
202
203
205
206
207
208
204
205
206
207
208
209
211
212
213
210
211
212
213
214

32 unmodified lines

// 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 contains the raw user prompts from the session. The store joins
    // and redacts them before persisting.
    Prompts []string

// FilesTouched are files modified during the session
151 unmodified lines

SkillEvents []types.SkillEvent

// PrecomputedBlobs, if non-nil, provides chunk blob hashes and the
    // content-hash blob hash computed once for this transcript. When set,
    // UpdateCommitted skips the per-call ChunkTranscript + zlib work and
    // reuses these hashes. Used by finalizeAllTurnCheckpoints to avoid
    // re-compressing identical content N times.
    // content-hash blob hash computed once for this transcript. When set, the
    // store skips per-call transcript chunking + compression and reuses these
    // hashes — e.g. to avoid re-compressing identical content across the
    // several checkpoints finalized together in one turn.
    PrecomputedBlobs *PrecomputedTranscriptBlobs
}

// PrecomputedTranscriptBlobs holds blob hashes for a transcript that was
// chunked and written to the object store once, for reuse across multiple
// UpdateCommitted calls sharing the same transcript content.
// Callers should avoid constructing this for empty transcripts; agent.ChunkTranscript
// would otherwise produce a single zero-length chunk and a hash for an empty
// blob, which downstream stores would never reference.
// transcript-backfill calls sharing the same transcript content.
// Callers should avoid constructing this for empty transcripts; transcript
// chunking would otherwise produce a single zero-length chunk and a hash for an
// empty blob, which downstream stores would never reference.
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).
    // Always non-empty when built for a non-empty transcript (which 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

Mapi/checkpoint/metadata.go+12/-14

1
2
3
3
4
5
6
7
8
9
10
11
38 unmodified lines

50
51
52
48
49
50
51
52
53
53
54
55
56
57
58
59
60
61
62
63
64
65
66

package checkpoint

import apicheckpoint "github.com/entireio/cli/api/checkpoint"
import (
    context

apicheckpoint "github.com/entireio/cli/api/checkpoint"
    "github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
)

// The committed-checkpoint contract (persisted document types, option types,
// reader/writer interfaces, and the Write request union) lives in the
38 unmodified lines

ErrNoTranscript       = apicheckpoint.ErrNoTranscript
)

// Contract helper functions, re-exported.
var (
    ReadCommittedCheckpoint        = apicheckpoint.ReadCommittedCheckpoint
    ReadLatestSessionContent       = apicheckpoint.ReadLatestSessionContent
    ReadRawSessionLogForCheckpoint = apicheckpoint.ReadRawSessionLogForCheckpoint
)
// Contract helper functions, re-exported as thin wrappers rather than vars so
// the facade symbols can't be reassigned by consumers.

func ReadCommittedCheckpoint(ctx context.Context, reader CommittedReader, checkpointID id.CheckpointID) (*CheckpointSummary, error) {
    return apicheckpoint.ReadCommittedCheckpoint(ctx, reader, checkpointID) //nolint:wrapcheck // thin re-export of the api/checkpoint helper
}

func ReadLatestSessionContent(ctx context.Context, reader CommittedReader, checkpointID id.CheckpointID, summary *CheckpointSummary) (*SessionContent, error) {
    return apicheckpoint.ReadLatestSessionContent(ctx, reader, checkpointID, summary) //nolint:wrapcheck // thin re-export of the api/checkpoint helper
}

func ReadRawSessionLogForCheckpoint(ctx context.Context, reader CommittedReader, checkpointID id.CheckpointID) ([]byte, string, error) {
    return apicheckpoint.ReadRawSessionLogForCheckpoint(ctx, reader, checkpointID) //nolint:wrapcheck // thin re-export of the api/checkpoint helper
}

Mcmd/entire/cli/checkpoint/aliases.go+20/-7