Documentation
¶
Overview ¶
Package id provides the CheckpointID type for identifying checkpoints. This is a separate package to avoid import cycles between paths, trailers, and checkpoint.
Index ¶
Constants ¶
const CheckpointPattern = `(?:` + Pattern + `|` + ulidPattern + `)`
CheckpointPattern matches a checkpoint ID in free text in either format (legacy 12-hex or ULID). Use this — not Pattern — when scanning text such as the Entire-Checkpoint commit trailer for a candidate checkpoint ID, then validate the captured token via NewCheckpointID/Validate (CheckpointPattern is a loose shape, not authoritative validation).
const Pattern = `[0-9a-f]{12}`
Pattern is the regex pattern for a legacy checkpoint ID: exactly 12 lowercase hex characters. Exported for use in other packages (e.g., trailers) to avoid pattern duplication. It is also reused by investigate/provenance for *run IDs*, which are always 12-hex — do NOT widen this to include ULIDs; use CheckpointPattern for matching a checkpoint ID that may be either format.
const ShortIDLength = 12
ShortIDLength is the standard length for truncating IDs for display purposes. Used for tool use IDs, session IDs, and commit hashes in logs and messages.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CheckpointID ¶
type CheckpointID string
CheckpointID identifies a checkpoint. It comes in two formats: a legacy 12-character lowercase hex ID and a 26-character Crockford base32 ULID (see Kind / CheckpointPattern). It links code commits to their checkpoint metadata.
const EmptyCheckpointID CheckpointID = ""
EmptyCheckpointID represents an unset or invalid checkpoint ID.
func Generate ¶
func Generate() (CheckpointID, error)
Generate creates a new random 12-character hex checkpoint ID.
Generation stays 12-hex regardless of storage backend. Emitting ULIDs is a separate, store-coupled change (new checkpoints get a ULID only under the git-refs store); this package only recognizes/validates both formats.
func MustCheckpointID ¶
func MustCheckpointID(s string) CheckpointID
MustCheckpointID creates a CheckpointID from a string, panicking if invalid. Use only when the ID is known to be valid (e.g., from trusted sources).
func NewCheckpointID ¶
func NewCheckpointID(s string) (CheckpointID, error)
NewCheckpointID creates a CheckpointID from a string, validating its format. Returns an error unless the string is a valid checkpoint ID (12-char hex or ULID).
func (CheckpointID) IsEmpty ¶
func (id CheckpointID) IsEmpty() bool
IsEmpty returns true if the checkpoint ID is empty or unset.
func (CheckpointID) MarshalJSON ¶
func (id CheckpointID) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler.
func (CheckpointID) Path ¶
func (id CheckpointID) Path() string
Path returns the sharded path for this checkpoint ID on entire/checkpoints/v1. Uses first 2 characters as shard (256 buckets), remaining as folder name. Example: "a3b2c4d5e6f7" -> "a3/b2c4d5e6f7"
func (CheckpointID) String ¶
func (id CheckpointID) String() string
String returns the checkpoint ID as a string.
func (*CheckpointID) UnmarshalJSON ¶
func (id *CheckpointID) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler with validation. Returns an error unless the JSON string is a valid checkpoint ID (12-char hex or ULID). Empty strings are allowed and result in EmptyCheckpointID.
Source Files