model

package
v0.4.2 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	GCStateMarked    = "marked"
	GCStateCommitted = "committed"
	GCStateFailed    = "failed"
)
View Source 
const GCPlanSchemaVersion = 1

Variables

This section is empty.

Functions

func NormalizeWorkspacePath deprecated 

func NormalizeWorkspacePath(raw string) (string, error)

NormalizeWorkspacePath normalizes a workspace-relative metadata key.

Deprecated: use NormalizeWorkspaceRelativePathKey. This function is not a filesystem safety validator and does not perform root-aware containment checks.

func NormalizeWorkspaceRelativePathKey 

func NormalizeWorkspaceRelativePathKey(raw string) (string, error)

NormalizeWorkspaceRelativePathKey normalizes a workspace-relative metadata key.

This is lexical normalization only. It does not resolve a workspace root, symlinks, filesystem aliases, or control paths such as .jvs. Code that reads, writes, restores, or materializes files must perform a separate root-aware canonical containment check before touching the filesystem.

Types

type AuditEventType 

type AuditEventType string

AuditEventType identifies the type of auditable event. 

const (
	EventTypeSnapshotCreate AuditEventType = "snapshot_create"
	EventTypeSnapshotDelete AuditEventType = "snapshot_delete"
	EventTypeRestore        AuditEventType = "restore"
	EventTypeWorktreeCreate AuditEventType = "worktree_create"
	EventTypeWorktreeRename AuditEventType = "worktree_rename"
	EventTypeWorktreeRemove AuditEventType = "worktree_remove"
	EventTypeGCPlan         AuditEventType = "gc_plan"
	EventTypeGCRun          AuditEventType = "gc_run"
)

type AuditRecord 

type AuditRecord struct {
	Timestamp    time.Time      `json:"timestamp"`
	EventType    AuditEventType `json:"event_type"`
	SnapshotID   SnapshotID     `json:"snapshot_id,omitempty"`
	WorktreeName string         `json:"worktree_name,omitempty"`
	Details      map[string]any `json:"details,omitempty"`
	PrevHash     HashValue      `json:"prev_hash"`
	RecordHash   HashValue      `json:"record_hash"`
}

AuditRecord is a single line in the audit log (JSONL format).

type CompressionInfo 

type CompressionInfo struct {
	Type  string `json:"type"`  // e.g., "gzip"
	Level int    `json:"level"` // Compression level (0-9)
}

CompressionInfo stores compression metadata for snapshots.

type Descriptor 

type Descriptor struct {
	SnapshotID           SnapshotID            `json:"snapshot_id"`
	ParentID             *SnapshotID           `json:"parent_id,omitempty"`
	StartedFrom          *SnapshotID           `json:"started_from,omitempty"`
	RestoredFrom         *SnapshotID           `json:"restored_from,omitempty"`
	RestoredPaths        []RestoredPathSource  `json:"restored_paths,omitempty"`
	WorktreeName         string                `json:"worktree_name"`
	CreatedAt            time.Time             `json:"created_at"`
	Note                 string                `json:"note,omitempty"`
	Tags                 []string              `json:"tags,omitempty"`
	Engine               EngineType            `json:"engine"`
	ActualEngine         EngineType            `json:"actual_engine,omitempty"`
	EffectiveEngine      EngineType            `json:"effective_engine,omitempty"`
	DegradedReasons      []string              `json:"degraded_reasons,omitempty"`
	MetadataPreservation *MetadataPreservation `json:"metadata_preservation,omitempty"`
	PerformanceClass     string                `json:"performance_class,omitempty"`
	PayloadRootHash      HashValue             `json:"payload_root_hash"`
	DescriptorChecksum   HashValue             `json:"descriptor_checksum"`
	IntegrityState       IntegrityState        `json:"integrity_state"`
	// PartialPaths is set for partial snapshots, listing the specific paths included.
	// Empty or nil means a full worktree snapshot.
	PartialPaths []string `json:"partial_paths,omitempty"`
	// Compression stores compression metadata if the snapshot is compressed.
	Compression *CompressionInfo `json:"compression,omitempty"`
}

Descriptor is the on-disk snapshot metadata.

type EngineType 

type EngineType string

EngineType identifies the snapshot engine type used for creating snapshots. 

const (
	EngineJuiceFSClone EngineType = "juicefs-clone"
	EngineReflinkCopy  EngineType = "reflink-copy"
	EngineCopy         EngineType = "copy"
)

type GCPlan 

type GCPlan struct {
	SchemaVersion          int             `json:"schema_version"`
	RepoID                 string          `json:"repo_id"`
	PlanID                 string          `json:"plan_id"`
	CreatedAt              time.Time       `json:"created_at"`
	ProtectedSet           []SnapshotID    `json:"protected_set"`
	ProtectedByLineage     int             `json:"protected_by_lineage"`
	CandidateCount         int             `json:"candidate_count"`
	ToDelete               []SnapshotID    `json:"to_delete"`
	DeletableBytesEstimate int64           `json:"deletable_bytes_estimate"`
	ProtectedByRetention   int             `json:"-"`
	RetentionPolicy        RetentionPolicy `json:"-"`
}

GCPlan is the output of gc plan phase.

type HashValue 

type HashValue string

HashValue is a SHA-256 hash stored as a hex string.

type IntegrityState 

type IntegrityState string

IntegrityState represents the verification status of a snapshot. 

const (
	IntegrityVerified IntegrityState = "verified"
	IntegrityTampered IntegrityState = "tampered"
	IntegrityUnknown  IntegrityState = "unknown"
)

type IntentRecord 

type IntentRecord struct {
	SnapshotID   SnapshotID `json:"snapshot_id"`
	WorktreeName string     `json:"worktree_name"`
	StartedAt    time.Time  `json:"started_at"`
	Engine       EngineType `json:"engine"`
}

IntentRecord tracks in-progress snapshot creation for crash recovery.

type InvalidRetentionPolicyError 

type InvalidRetentionPolicyError struct {
	Field  string
	Reason string
	Value  interface{}
}

InvalidRetentionPolicyError is returned when a retention policy is invalid.

func (*InvalidRetentionPolicyError) Error 

func (e *InvalidRetentionPolicyError) Error() string

type MetadataPreservation 

type MetadataPreservation struct {
	Symlinks   string `json:"symlinks"`
	Hardlinks  string `json:"hardlinks"`
	Mode       string `json:"mode"`
	Timestamps string `json:"timestamps"`
	Ownership  string `json:"ownership,omitempty"`
	Xattrs     string `json:"xattrs"`
	ACLs       string `json:"acls"`
}

MetadataPreservation describes metadata semantics for an engine choice.

type PathDirtySet 

type PathDirtySet map[string]PathDirtyState

PathDirtySet tracks known workspace-relative dirty keys and clean exceptions.

func NewPathDirtySet 

func NewPathDirtySet() PathDirtySet

NewPathDirtySet returns an empty path dirty set.

func (*PathDirtySet) ClearPath 

func (ds *PathDirtySet) ClearPath(rawPath string) error

ClearPath clears dirty markers known to be inside path.

func (PathDirtySet) Clone 

func (ds PathDirtySet) Clone() PathDirtySet

Clone returns an independent dirty set copy.

func (PathDirtySet) Contains 

func (ds PathDirtySet) Contains(rawPath string) bool

Contains reports whether path is covered by a known dirty marker.

func (PathDirtySet) HasDirty 

func (ds PathDirtySet) HasDirty() bool

HasDirty reports whether the set still contains any dirty marker.

func (*PathDirtySet) Mark 

func (ds *PathDirtySet) Mark(rawPath string) error

Mark records path as dirty, coalescing redundant descendant markers.

type PathDirtyState 

type PathDirtyState string

PathDirtyState marks whether a workspace-relative key is dirty or a clean exception under a broader dirty marker. 

const (
	PathDirty PathDirtyState = "dirty"
	PathClean PathDirtyState = "clean"
)

type PathSource 

type PathSource struct {
	SourceSnapshotID SnapshotID          `json:"source_snapshot_id"`
	SourcePath       string              `json:"source_path"`
	Status           PathSourceStatus    `json:"status"`
	Evidence         *PathSourceEvidence `json:"evidence,omitempty"`
}

PathSource records where a workspace path was most recently restored from.

type PathSourceEvidence 

type PathSourceEvidence struct {
	Hash HashValue `json:"hash,omitempty"`
}

PathSourceEvidence stores optional evidence captured for a path source.

type PathSourceStatus 

type PathSourceStatus string

PathSourceStatus describes whether a restored path still exactly matches its source. 

const (
	PathSourceExact                PathSourceStatus = "exact"
	PathSourceModifiedAfterRestore PathSourceStatus = "modified_after_restore"
	PathSourceUnresolved           PathSourceStatus = "unresolved"
)

type PathSources 

type PathSources map[string]PathSource

PathSources maps normalized workspace-relative target paths to their sources.

func NewPathSources 

func NewPathSources() PathSources

NewPathSources returns an empty path source set.

func (PathSources) Clone 

func (ps PathSources) Clone() PathSources

Clone returns an independent copy of path sources.

func (*PathSources) MarkDeleted 

func (ps *PathSources) MarkDeleted(rawPath string) error

MarkDeleted clears deleted restored paths and downgrades containing restored directories.

func (*PathSources) MarkModified 

func (ps *PathSources) MarkModified(rawPath string) error

MarkModified downgrades matching path source provenance after an edit.

func (*PathSources) Restore 

func (ps *PathSources) Restore(targetPath string, source SnapshotID) error

Restore records that targetPath was restored from the same path in source.

func (*PathSources) RestoreFromPath 

func (ps *PathSources) RestoreFromPath(targetPath string, source SnapshotID, sourcePath string) error

RestoreFromPath records that targetPath was restored from sourcePath in source.

func (PathSources) RestoredPaths 

func (ps PathSources) RestoredPaths() []RestoredPathSource

RestoredPaths returns a stable save-point provenance copy sorted by target path.

func (PathSources) SourceForPath 

func (ps PathSources) SourceForPath(rawPath string) (RestoredPathSource, bool, error)

SourceForPath returns the most-specific source entry that applies to path.

type Pin 

type Pin struct {
	PinID      string     `json:"pin_id,omitempty"`
	SnapshotID SnapshotID `json:"snapshot_id"`
	PinnedAt   time.Time  `json:"pinned_at,omitempty"`
	CreatedAt  time.Time  `json:"created_at,omitempty"`
	Reason     string     `json:"reason,omitempty"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
}

Pin protects a snapshot from garbage collection.

type ReadyMarker 

type ReadyMarker struct {
	SnapshotID         SnapshotID `json:"snapshot_id"`
	CompletedAt        time.Time  `json:"completed_at"`
	PayloadHash        HashValue  `json:"payload_root_hash"`
	Engine             EngineType `json:"engine"`
	DescriptorChecksum HashValue  `json:"descriptor_checksum"`
}

ReadyMarker is the .READY file content indicating complete snapshot.

type RestoredPathSource 

type RestoredPathSource struct {
	TargetPath       string              `json:"target_path"`
	SourceSnapshotID SnapshotID          `json:"source_snapshot_id"`
	SourcePath       string              `json:"source_path"`
	Status           PathSourceStatus    `json:"status"`
	Evidence         *PathSourceEvidence `json:"evidence,omitempty"`
}

RestoredPathSource is the save-point provenance form of a path source.

type RetentionPolicy 

type RetentionPolicy struct {
	// KeepMinSnapshots ensures at least N snapshots are always kept.
	// The most recent snapshots by creation time are protected.
	KeepMinSnapshots int `json:"-"`

	// KeepMinAge protects snapshots younger than this duration.
	// Snapshots created within this time window are never deleted.
	KeepMinAge time.Duration `json:"-"`
}

RetentionPolicy configures internal compatibility retention rules. The v0 public CLI does not expose retention flags; default GC protection is live workspace lineage plus in-progress operation intents.

Snapshots are protected if they match ANY of these rules: - Within the last N snapshots (KeepMinSnapshots) - Created within the last duration (KeepMinAge) - Part of a worktree's lineage

func DefaultRetentionPolicy 

func DefaultRetentionPolicy() RetentionPolicy

DefaultRetentionPolicy returns the default retention policy.

func (*RetentionPolicy) Validate 

func (rp *RetentionPolicy) Validate() error

Validate checks if the retention policy is valid.

type SnapshotID 

type SnapshotID string

SnapshotID is the unique identifier for a snapshot: <unix_ms>-<rand8hex>

func NewSnapshotID 

func NewSnapshotID() SnapshotID

NewSnapshotID generates a new unique snapshot ID.

func (SnapshotID) IsValid 

func (id SnapshotID) IsValid() bool

IsValid reports whether id is in canonical on-disk snapshot ID form.

func (SnapshotID) ShortID 

func (id SnapshotID) ShortID() string

ShortID returns the first 8 characters for display.

func (SnapshotID) String 

func (id SnapshotID) String() string

String returns the full snapshot ID as string.

func (SnapshotID) Validate 

func (id SnapshotID) Validate() error

Validate rejects non-canonical or path-like snapshot IDs.

type Tombstone 

type Tombstone struct {
	SnapshotID  SnapshotID `json:"snapshot_id"`
	DeletedAt   time.Time  `json:"deleted_at"`
	Reclaimable bool       `json:"reclaimable"`
	GCState     string     `json:"gc_state,omitempty"`
	Reason      string     `json:"reason,omitempty"`
}

Tombstone marks a snapshot as deleted but not yet reclaimed.

type WorkspaceSaveLineage 

type WorkspaceSaveLineage struct {
	SnapshotID    SnapshotID           `json:"snapshot_id,omitempty"`
	ParentID      *SnapshotID          `json:"parent_id,omitempty"`
	StartedFrom   *SnapshotID          `json:"started_from,omitempty"`
	RestoredFrom  *SnapshotID          `json:"restored_from,omitempty"`
	RestoredPaths []RestoredPathSource `json:"restored_paths,omitempty"`
}

WorkspaceSaveLineage is the creation-time lineage/provenance for the next save.

func (WorkspaceSaveLineage) ApplyToDescriptor 

func (l WorkspaceSaveLineage) ApplyToDescriptor(desc *Descriptor)

ApplyToDescriptor copies lineage/provenance into a snapshot descriptor.

type WorkspaceState 

type WorkspaceState struct {
	HistoryHead              *SnapshotID  `json:"history_head,omitempty"`
	ContentSource            *SnapshotID  `json:"content_source,omitempty"`
	StartedFrom              *SnapshotID  `json:"started_from,omitempty"`
	PathSources              PathSources  `json:"path_sources,omitempty"`
	DirtyPaths               PathDirtySet `json:"dirty_paths,omitempty"`
	HasUnknownUnsavedChanges bool         `json:"has_unknown_unsaved_changes,omitempty"`
	HasUnsavedChanges        bool         `json:"has_unsaved_changes"`
}

WorkspaceState captures the workspace-local state needed by save point semantics.

func WorkspaceStateAtSavePoint 

func WorkspaceStateAtSavePoint(head SnapshotID) WorkspaceState

WorkspaceStateAtSavePoint returns a clean workspace whose files match head.

func WorkspaceStateStartedFrom 

func WorkspaceStateStartedFrom(source SnapshotID) WorkspaceState

WorkspaceStateStartedFrom returns the initial state for workspace new --from.

func (*WorkspaceState) MarkPathDeleted 

func (s *WorkspaceState) MarkPathDeleted(path string) error

MarkPathDeleted records a path deletion in the path-source provenance and marks the workspace dirty.

func (*WorkspaceState) MarkPathModified 

func (s *WorkspaceState) MarkPathModified(path string) error

MarkPathModified records a path edit in the path-source provenance and marks the workspace dirty.

func (*WorkspaceState) MarkUnsaved 

func (s *WorkspaceState) MarkUnsaved()

MarkUnsaved records that managed files have changed since the known source state.

func (WorkspaceState) NextSaveLineage 

func (s WorkspaceState) NextSaveLineage(newSave SnapshotID) WorkspaceSaveLineage

NextSaveLineage computes creation-time lineage without mutating workspace state.

func (*WorkspaceState) RestorePath 

func (s *WorkspaceState) RestorePath(path string, source SnapshotID) error

RestorePath records path-level restore provenance without moving history.

func (*WorkspaceState) RestoreWhole 

func (s *WorkspaceState) RestoreWhole(source SnapshotID)

RestoreWhole records a whole-workspace materialization without moving history.

func (*WorkspaceState) Save 

func (s *WorkspaceState) Save(newSave SnapshotID) WorkspaceSaveLineage

Save computes creation-time lineage for newSave and moves the workspace to it.

type WorktreeConfig 

type WorktreeConfig struct {
	Name                  string      `json:"name"`
	RealPath              string      `json:"real_path,omitempty"`          // Canonical real folder path for adopted workspaces
	BaseSnapshotID        SnapshotID  `json:"base_snapshot_id,omitempty"`   // Immutable snapshot worktree was created from
	HeadSnapshotID        SnapshotID  `json:"head_snapshot_id,omitempty"`   // Current position (may differ from latest if detached)
	LatestSnapshotID      SnapshotID  `json:"latest_snapshot_id,omitempty"` // The most recent snapshot in this worktree's lineage
	StartedFromSnapshotID SnapshotID  `json:"started_from,omitempty"`       // Initial content source for a workspace with no inherited history
	PathSources           PathSources `json:"path_sources,omitempty"`       // Path-level restore provenance for the active workspace
	CreatedAt             time.Time   `json:"created_at"`
}

WorktreeConfig is stored at .jvs/worktrees/<name>/config.json

func (*WorktreeConfig) CanSnapshot 

func (c *WorktreeConfig) CanSnapshot() bool

CanSnapshot returns true if the worktree can create new snapshots. A worktree can snapshot if it has no snapshots yet (first snapshot) or if it is at HEAD (not detached).

func (*WorktreeConfig) IsDetached 

func (c *WorktreeConfig) IsDetached() bool

IsDetached returns true if the worktree is at a historical snapshot (not at HEAD). A worktree is in "detached" state when HeadSnapshotID differs from LatestSnapshotID.

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.