repo

package
v0.4.7 Latest Latest
Warning

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

 Go to latest Published: May 5, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package repo handles JVS repository initialization and discovery.

Index

Constants

View Source 
const (
	// FormatVersion is the current repository format version.
	FormatVersion = 1
	// JVSDirName is the name of the JVS metadata directory.
	JVSDirName = ".jvs"
	// FormatVersionFile is the name of the file storing the format version.
	FormatVersionFile = "format_version"
	// RepoIDFile is the name of the file storing the repository ID.
	RepoIDFile = "repo_id"
	// RepoModeFile is the durable metadata file storing the repository mode.
	RepoModeFile = "repo_mode"
	// RepoModeEmbeddedControl is the classic repo layout with .jvs under the payload root.
	RepoModeEmbeddedControl = "embedded_control"
	// RepoModeSeparatedControl is the layout with trusted control and payload roots split.
	RepoModeSeparatedControl = "separated_control"
)

Variables

View Source 
var (
	// ErrControlRepoNotFound marks a control-repo walk that reached the filesystem root.
	ErrControlRepoNotFound = errors.New("control repository not found")
)

Functions

func DescriptorsDirPath 

func DescriptorsDirPath(repoRoot string) (string, error)

DescriptorsDirPath returns the descriptors control directory after validating it.

func GCDirPath 

func GCDirPath(repoRoot string) (string, error)

GCDirPath returns the GC control directory after validating it.

func GCPinPathForRead 

func GCPinPathForRead(repoRoot, pinFileName string) (string, error)

GCPinPathForRead returns an existing documented GC pin path after rejecting a symlink or wrong-type final leaf.

func GCPinsDirPath 

func GCPinsDirPath(repoRoot string) (string, error)

GCPinsDirPath returns the documented GC pins control directory after validating it.

func GCPlanPath 

func GCPlanPath(repoRoot, planID string) (string, error)

GCPlanPath returns the path for a GC plan ID after rejecting path-like names.

func GCPlanPathForDelete 

func GCPlanPathForDelete(repoRoot, planID string) (string, error)

GCPlanPathForDelete returns a GC plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCPlanPathForRead 

func GCPlanPathForRead(repoRoot, planID string) (string, error)

GCPlanPathForRead returns an existing GC plan path after rejecting a symlink or wrong-type final leaf.

func GCPlanPathForWrite 

func GCPlanPathForWrite(repoRoot, planID string) (string, error)

GCPlanPathForWrite returns a GC plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCTombstonePath 

func GCTombstonePath(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePath returns the tombstone path for a canonical snapshot ID.

func GCTombstonePathForDelete 

func GCTombstonePathForDelete(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePathForDelete returns a tombstone path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCTombstonePathForRead 

func GCTombstonePathForRead(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePathForRead returns an existing tombstone path after rejecting a symlink or wrong-type final leaf.

func GCTombstonePathForWrite 

func GCTombstonePathForWrite(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePathForWrite returns a tombstone path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCTombstonesDirPath 

func GCTombstonesDirPath(repoRoot string) (string, error)

GCTombstonesDirPath returns the tombstones control directory after validating it.

func IntentPath 

func IntentPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

IntentPath returns the intent record path for a canonical snapshot ID.

func IntentsDirPath 

func IntentsDirPath(repoRoot string) (string, error)

IntentsDirPath returns the intents control directory after validating it.

func LegacyPinPathForRead 

func LegacyPinPathForRead(repoRoot, pinFileName string) (string, error)

LegacyPinPathForRead returns an existing legacy pin path after rejecting a symlink or wrong-type final leaf.

func LegacyPinsDirPath 

func LegacyPinsDirPath(repoRoot string) (string, error)

LegacyPinsDirPath returns the legacy pins control directory after validating it.

func LoadRepoMode added in v0.4.7 

func LoadRepoMode(repoRoot string) (string, error)

LoadRepoMode reads the durable repository mode. Repositories created before the mode file existed are embedded-control repos by definition.

func LoadWorktreeConfig 

func LoadWorktreeConfig(repoRoot, name string) (*model.WorktreeConfig, error)

LoadWorktreeConfig loads a worktree config.

func MarkWorkspaceLocatorPendingLifecycle added in v0.4.7 

func MarkWorkspaceLocatorPendingLifecycle(req MarkWorkspaceLocatorPendingLifecycleRequest) error

MarkWorkspaceLocatorPendingLifecycle writes recovery evidence into an external workspace locator only when the current locator still matches the expected operation identity.

func RecoveryPlanPath 

func RecoveryPlanPath(repoRoot, planID string) (string, error)

RecoveryPlanPath returns the path for a recovery plan ID after rejecting path-like names.

func RecoveryPlanPathForRead 

func RecoveryPlanPathForRead(repoRoot, planID string) (string, error)

RecoveryPlanPathForRead returns an existing recovery plan path after rejecting a symlink or wrong-type final leaf.

func RecoveryPlanPathForWrite 

func RecoveryPlanPathForWrite(repoRoot, planID string) (string, error)

RecoveryPlanPathForWrite returns a recovery plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func RecoveryPlansDirPath 

func RecoveryPlansDirPath(repoRoot string) (string, error)

RecoveryPlansDirPath returns the recovery plan control directory after validating it.

func RestorePlanPath 

func RestorePlanPath(repoRoot, planID string) (string, error)

RestorePlanPath returns the path for a restore operation plan ID after rejecting path-like names.

func RestorePlanPathForRead 

func RestorePlanPathForRead(repoRoot, planID string) (string, error)

RestorePlanPathForRead returns an existing restore plan path after rejecting a symlink or wrong-type final leaf.

func RestorePlanPathForWrite 

func RestorePlanPathForWrite(repoRoot, planID string) (string, error)

RestorePlanPathForWrite returns a restore plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func RewriteWorkspaceLocator added in v0.4.7 

func RewriteWorkspaceLocator(req RewriteWorkspaceLocatorRequest) error

RewriteWorkspaceLocator rewrites an external workspace locator only after the existing locator matches all expected identity fields.

func SnapshotDescriptorPath 

func SnapshotDescriptorPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPath returns the descriptor path for a canonical snapshot ID.

func SnapshotDescriptorPathForDelete 

func SnapshotDescriptorPathForDelete(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPathForDelete returns a descriptor path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func SnapshotDescriptorPathForRead 

func SnapshotDescriptorPathForRead(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPathForRead returns an existing descriptor path after rejecting a symlink or wrong-type final leaf.

func SnapshotDescriptorPathForWrite 

func SnapshotDescriptorPathForWrite(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPathForWrite returns a descriptor path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func SnapshotPath 

func SnapshotPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotPath returns the on-disk snapshot storage path for a canonical ID.

func SnapshotPathForDelete 

func SnapshotPathForDelete(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotPathForDelete returns a snapshot directory path after rejecting a symlink or wrong-type final leaf. Missing leaves are allowed for idempotent delete/retry paths.

func SnapshotPathForRead 

func SnapshotPathForRead(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotPathForRead returns an existing snapshot directory path after rejecting a symlink or wrong-type final leaf.

func SnapshotTmpPath 

func SnapshotTmpPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotTmpPath returns the unpublished temporary snapshot path for a canonical ID.

func SnapshotsDirPath 

func SnapshotsDirPath(repoRoot string) (string, error)

SnapshotsDirPath returns the snapshots control directory after validating it.

func ValidateInitTarget 

func ValidateInitTarget(path string) (string, error)

ValidateInitTarget returns the absolute target path after enforcing the repository creation rules: the target must be missing or empty, must not already contain .jvs metadata, and must not be lexically or physically nested inside a JVS repo.

func ValidateManagedPayloadOnly 

func ValidateManagedPayloadOnly(boundary WorktreePayloadBoundary, payloadRoot string) error

ValidateManagedPayloadOnly verifies that a materialized payload source does not contain root-level control data excluded from the managed workspace.

func ValidateSeparatedPayloadSymlinkBoundary added in v0.4.7 

func ValidateSeparatedPayloadSymlinkBoundary(ctx *SeparatedContext) error

ValidateSeparatedPayloadSymlinkBoundary walks a separated payload and rejects symlinks that resolve outside the payload or into the control root.

func ValidateWorkspaceLocatorEvidence added in v0.4.7 

func ValidateWorkspaceLocatorEvidence(start, boundary string) error

ValidateWorkspaceLocatorEvidence walks from start toward boundary and returns malformed workspace locator errors found before accepting a physical ancestor. Well-formed locator files are ignored so a child workspace locator cannot override the physical repository selected by the caller.

func ValidateWorktreeRealPathForRepair 

func ValidateWorktreeRealPathForRepair(repoRoot, name, realPath string) (string, error)

ValidateWorktreeRealPathForRepair validates a replacement real path and returns the canonical physical path that should be stored.

func ValidateWorktreeRealPathRegistry 

func ValidateWorktreeRealPathRegistry(repoRoot string) error

ValidateWorktreeRealPathRegistry verifies that registered workspace payload roots do not overlap each other or point into repository control data.

func WithMutationLock 

func WithMutationLock(repoRoot, operation string, fn func() error) error

WithMutationLock acquires the repository mutation lock, runs fn, and always releases the lock before returning.

func WorkspaceLocatorMatchesRepo added in v0.4.7 

func WorkspaceLocatorMatchesRepo(workspaceRoot, repoRoot string) (bool, error)

WorkspaceLocatorMatchesRepo reports whether workspaceRoot contains a valid workspace locator that currently resolves to repoRoot. A locator with an offline or otherwise stale repo_root is treated as a non-match so repair can rewrite it.

func WorkspaceLocatorMatchesRepoWorkspace added in v0.4.7 

func WorkspaceLocatorMatchesRepoWorkspace(workspaceRoot, repoRoot, workspaceName string) (bool, error)

WorkspaceLocatorMatchesRepoWorkspace reports whether workspaceRoot has a valid locator for the exact repo identity and workspace name.

func WorkspaceLocatorPresent added in v0.4.7 

func WorkspaceLocatorPresent(workspaceRoot string) (bool, error)

WorkspaceLocatorPresent reports whether workspaceRoot contains a JVS workspace locator file.

func WorktreeConfigDirPath 

func WorktreeConfigDirPath(repoRoot, name string) (string, error)

WorktreeConfigDirPath returns the metadata directory for a worktree.

func WorktreeConfigPath 

func WorktreeConfigPath(repoRoot, name string) (string, error)

WorktreeConfigPath returns the path to a worktree's config.json.

func WorktreePayloadPath 

func WorktreePayloadPath(repoRoot, name string) (string, error)

WorktreePayloadPath returns the payload directory for a worktree.

func WorktreesDirPath 

func WorktreesDirPath(repoRoot string) (string, error)

WorktreesDirPath returns the worktrees control directory after validating it.

func WriteDetachedWorkspaceLocator added in v0.4.7 

func WriteDetachedWorkspaceLocator(req DetachWorkspaceLocatorRequest) error

WriteDetachedWorkspaceLocator rewrites an external workspace locator to a detached/orphaned marker after verifying the previous active identity.

func WriteWorkspaceLocator added in v0.4.7 

func WriteWorkspaceLocator(workspaceRoot, repoRoot, workspaceName string) error

WriteWorkspaceLocator makes an external workspace discover its owning repository when users run jvs from inside that workspace folder.

func WriteWorktreeConfig 

func WriteWorktreeConfig(repoRoot, name string, cfg *model.WorktreeConfig) error

WriteWorktreeConfig atomically writes a worktree config.

Types

type DetachWorkspaceLocatorRequest added in v0.4.7 

type DetachWorkspaceLocatorRequest struct {
	WorkspaceRoot          string
	ExpectedRepoID         string
	ExpectedRepoRoot       string
	ExpectedWorkspaceName  string
	OperationID            string
	DetachedAt             time.Time
	RecommendedNextCommand string
}

DetachWorkspaceLocatorRequest marks a previously active external workspace locator as intentionally detached/orphaned. The rewrite only commits when the active locator still matches the expected repo and workspace identity, or when the locator is already detached by the same operation.

type MarkWorkspaceLocatorPendingLifecycleRequest added in v0.4.7 

type MarkWorkspaceLocatorPendingLifecycleRequest struct {
	WorkspaceRoot          string
	ExpectedRepoID         string
	ExpectedRepoRoot       string
	ExpectedWorkspaceName  string
	OperationID            string
	OperationType          string
	Phase                  string
	SourceRepoRoot         string
	TargetRepoRoot         string
	RecommendedNextCommand string
}

MarkWorkspaceLocatorPendingLifecycleRequest records pending lifecycle recovery evidence without changing the locator's current repo_root binding.

type MutationLock 

type MutationLock struct {
	// contains filtered or unexported fields
}

MutationLock is a no-wait repository-wide lock for metadata/payload mutations. It is implemented with atomic mkdir so contenders fail immediately with E_REPO_BUSY instead of blocking.

func AcquireMutationLock 

func AcquireMutationLock(repoRoot, operation string) (*MutationLock, error)

AcquireMutationLock attempts to acquire the repository mutation lock without waiting. Call Release when the mutation is complete.

func (*MutationLock) Release 

func (l *MutationLock) Release() error

Release releases the mutation lock. It is safe to call more than once.

type MutationLockInspection 

type MutationLockInspection struct {
	Path         string
	OwnerPath    string
	Owner        *MutationLockOwner
	Status       MutationLockStatus
	SafeToRemove bool
	Reason       string
}

MutationLockInspection is a fail-closed view of the repository mutation lock.

func InspectMutationLock 

func InspectMutationLock(repoRoot string) (MutationLockInspection, error)

InspectMutationLock returns a non-mutating, fail-closed view of repo.lock.

func RemoveStaleMutationLock 

func RemoveStaleMutationLock(repoRoot string) (MutationLockInspection, bool, error)

RemoveStaleMutationLock removes repo.lock only when inspection proves the owner is on this host, the process is gone, and the lock is old enough.

type MutationLockOwner 

type MutationLockOwner struct {
	Operation string    `json:"operation"`
	PID       int       `json:"pid"`
	Hostname  string    `json:"hostname,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

MutationLockOwner is the process identity written by the lock holder.

type MutationLockStatus 

type MutationLockStatus string

MutationLockStatus describes the observed state of the repository mutation lock. 

const (
	MutationLockAbsent  MutationLockStatus = "absent"
	MutationLockHeld    MutationLockStatus = "held"
	MutationLockStale   MutationLockStatus = "stale"
	MutationLockInvalid MutationLockStatus = "invalid"
)

type Repo 

type Repo struct {
	Root          string
	FormatVersion int
	RepoID        string
	Mode          string
}

Repo represents an initialized JVS repository.

func Discover 

func Discover(cwd string) (*Repo, error)

Discover walks up from cwd to find the repo root (directory containing .jvs/).

func DiscoverControlRepo added in v0.4.7 

func DiscoverControlRepo(cwd string) (*Repo, error)

DiscoverControlRepo walks up from cwd looking only for repository control directories. It intentionally ignores workspace locator files so callers can detect the physical ancestor repository even when a child locator is forged or malformed.

func DiscoverPendingLifecycleRepoFromWorkspace added in v0.4.7 

func DiscoverPendingLifecycleRepoFromWorkspace(cwd, sourceRepoRoot string) (*Repo, error)

DiscoverPendingLifecycleRepoFromWorkspace resolves a moved repo root using only the pending lifecycle marker in cwd's workspace locator. It is used for recommended --repo <old-root> recovery commands after the old root no longer exists.

func DiscoverWorktree 

func DiscoverWorktree(cwd string) (*Repo, string, error)

DiscoverWorktree discovers the repo and maps cwd to a worktree name.

func Init 

func Init(path string, name string) (*Repo, error)

Init creates a new JVS repository at the specified path.

func InitAdoptedWorkspace 

func InitAdoptedWorkspace(folder string) (*Repo, error)

InitAdoptedWorkspace initializes JVS control data inside an existing folder and registers that folder itself as the main workspace payload.

func InitSeparatedControl added in v0.4.7 

func InitSeparatedControl(controlRoot, payloadRoot, workspaceName string) (*Repo, error)

InitSeparatedControl creates a repo whose trusted control plane lives under controlRoot while the main workspace payload lives under payloadRoot.

func InitTarget 

func InitTarget(path string) (*Repo, error)

InitTarget creates a new repository at an absolute or relative target path.

func OpenControlRoot added in v0.4.7 

func OpenControlRoot(controlRoot string) (*Repo, error)

OpenControlRoot opens exactly the supplied control root. It does not walk cwd and does not read workspace locators.

type RewriteWorkspaceLocatorRequest added in v0.4.7 

type RewriteWorkspaceLocatorRequest struct {
	WorkspaceRoot         string
	ExpectedRepoID        string
	ExpectedRepoRoot      string
	ExpectedWorkspaceName string
	NewRepoRoot           string
	NewWorkspaceName      string
}

RewriteWorkspaceLocatorRequest updates a locator only when every expected identity field still matches the on-disk record.

type SeparatedContext added in v0.4.7 

type SeparatedContext struct {
	Repo                 *Repo
	ControlRoot          string
	PayloadRoot          string
	Workspace            string
	BoundaryValidated    bool
	LocatorAuthoritative bool
}

SeparatedContext is the resolved authority and payload binding for a separated-control workspace.

func ResolveSeparatedContext added in v0.4.7 

func ResolveSeparatedContext(req SeparatedContextRequest) (*SeparatedContext, error)

ResolveSeparatedContext resolves a workspace from a separated control root using only the explicit control root and the workspace registry.

func RevalidateSeparatedContext added in v0.4.7 

func RevalidateSeparatedContext(req SeparatedContextRevalidationRequest) (*SeparatedContext, error)

RevalidateSeparatedContext resolves the separated-control binding again and verifies the control repo identity and registry payload root still match the previously resolved separated context.

type SeparatedContextRequest added in v0.4.7 

type SeparatedContextRequest struct {
	ControlRoot string
	Workspace   string
}

SeparatedContextRequest explicitly selects a separated-control repository. It intentionally has no cwd field so callers cannot accidentally fall back to ambient discovery or a payload-side locator.

type SeparatedContextRevalidationRequest added in v0.4.7 

type SeparatedContextRevalidationRequest struct {
	ControlRoot string
	Workspace   string
	// ExpectedRepoID is the repo_id captured from the previously resolved
	// separated context.
	ExpectedRepoID string
	// ExpectedPayloadRoot is the payload root captured from the previously
	// resolved separated context.
	ExpectedPayloadRoot string
}

SeparatedContextRevalidationRequest re-checks a previously resolved separated-control workspace binding before a mutation or re-read.

type WorkspaceLocator added in v0.4.7 

type WorkspaceLocator = workspaceLocatorFile

WorkspaceLocator is the external workspace discovery record stored at <workspace>/.jvs.

func ReadWorkspaceLocator added in v0.4.7 

func ReadWorkspaceLocator(workspaceRoot string) (WorkspaceLocator, bool, error)

ReadWorkspaceLocator reads a workspace locator from workspaceRoot when one is present. A missing locator returns ok=false and nil error.

type WorkspaceLocatorCheck added in v0.4.7 

type WorkspaceLocatorCheck struct {
	WorkspaceRoot         string
	ExpectedRepoRoot      string
	ExpectedRepoID        string
	ExpectedWorkspaceName string
}

WorkspaceLocatorCheck is an expected-identity locator inspection request.

type WorkspaceLocatorDiagnostic added in v0.4.7 

type WorkspaceLocatorDiagnostic struct {
	Present bool
	Matches bool
	Reason  string
	Locator WorkspaceLocator
}

WorkspaceLocatorDiagnostic reports whether a locator matched the expected repo and workspace identity, with a stable reason for fail-closed callers.

func InspectWorkspaceLocator added in v0.4.7 

func InspectWorkspaceLocator(check WorkspaceLocatorCheck) (WorkspaceLocatorDiagnostic, error)

InspectWorkspaceLocator compares a workspace locator with expected repo and workspace identity without guessing or repairing mismatches.

type WorkspaceLocatorPendingLifecycle added in v0.4.7 

type WorkspaceLocatorPendingLifecycle struct {
	OperationID            string `json:"operation_id"`
	OperationType          string `json:"operation_type"`
	RepoID                 string `json:"repo_id"`
	Phase                  string `json:"phase"`
	SourceRepoRoot         string `json:"source_repo_root"`
	TargetRepoRoot         string `json:"target_repo_root"`
	RecommendedNextCommand string `json:"recommended_next_command"`
}

WorkspaceLocatorPendingLifecycle is durable recovery evidence written into an external workspace locator before moving a repo root.

type WorktreePayloadBoundary 

type WorktreePayloadBoundary struct {
	Root              string
	ExcludedRootNames []string
}

WorktreePayloadBoundary describes the managed portion of a worktree payload.

func WorktreeManagedPayloadBoundary 

func WorktreeManagedPayloadBoundary(repoRoot, name string) (WorktreePayloadBoundary, error)

WorktreeManagedPayloadBoundary returns the managed payload root and any root-level control paths that must be excluded from captures.

func (WorktreePayloadBoundary) ExcludesRelativePath 

func (b WorktreePayloadBoundary) ExcludesRelativePath(rel string) bool

ExcludesRelativePath reports whether rel is outside the managed payload because it is reserved for repository control data.

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.