Documentation
¶
Overview ¶
Package repository provides durable graph storage and repository lifecycle operations.
Package repository provides durable graph storage and repository lifecycle operations.
Index ¶
- Constants
- Variables
- func FindWorkspaceByID(root string, id WorkspaceID) (string, error)
- func MigrateRepositoryFormatV1ToV2(stateDir string) error
- func ReconciliationBranchName(branch string) string
- func RepositoryWorkspacePath(root string, id WorkspaceID) (string, error)
- func UpdateWorkspaceRegistry(root string, update func(*WorkspaceRegistry) error) error
- func ValidateSchemaSnapshot(schema SchemaSnapshot, nodes map[string]Node, edges map[string]Edge) error
- func WorkspaceStorageRoot() (string, error)
- func WriteWorkspaceManifest(repositoryRoot string, manifest WorkspaceManifest) error
- type AssetAddRequest
- type AssetAddResult
- type AssetMetadata
- type AssetStore
- type BranchContainmentResult
- type BranchCreateRequest
- type BranchCreateResult
- type BranchDeleteRequest
- type BranchDeleteResult
- type BranchListResult
- type BranchSource
- type BranchStagingStatus
- type BranchSwitchRequest
- type BranchSwitchResult
- type BranchesContainingRequest
- type Cardinality
- type CherryPickChange
- type CherryPickCommittedWithWarningError
- type CherryPickConflict
- type CherryPickRequest
- type CherryPickResult
- type CherryPickSchemaViolation
- type CommitStagedMutationRequest
- type CommitStagedMutationResult
- type CommittedWithWarningError
- type ContainmentSelector
- type DiffContext
- type DiffEntry
- type DiffFilter
- type DiffRequest
- type DiffResult
- type Edge
- type EdgeTypeRule
- type FilterNodesRequest
- type FilterNodesResult
- type FsckDiagnostic
- type FsckError
- type FsckResult
- type GCCommittedWithWarningError
- type GCOptions
- type GCResult
- type GlobalInvariant
- type GraphSnapshot
- type HistoryEntry
- type HistoryRequest
- type HistoryResult
- type ImpactEntry
- type ImpactRequest
- type ImpactResult
- type Initialization
- type InstallPullResult
- type MergeChange
- type MergeConflict
- type MergePreview
- type MergePreviewBinding
- type MergeResolutionSelection
- type MergeTransactionStatus
- type MetadataPredicate
- type MigrationResult
- type MutationOperation
- type Node
- type NodeLabelRule
- type ObjectID
- type PackCompression
- type PackCorruptionError
- type PackID
- type PackIndexEntry
- type PackManifest
- type PackMetadata
- type PerformancePhase
- type PerformanceRecorder
- type PinnedSnapshotRecord
- type ProjectionStatus
- type PropertyKind
- type PropertyRule
- type PropertyValue
- func BoolPropertyValue(value bool) PropertyValue
- func FloatPropertyValue(value float64) PropertyValue
- func IntegerPropertyValue(value int64) PropertyValue
- func ListPropertyValue(value []PropertyValue) PropertyValue
- func MapPropertyValue(value map[string]PropertyValue) PropertyValue
- func NullPropertyValue() PropertyValue
- func StringPropertyValue(value string) PropertyValue
- type PropertyValueKind
- type PruneCommittedWithWarningError
- type PruneRequest
- type PruneResult
- type PushCommitRecord
- type PushObject
- type PushPack
- type ReconcileResult
- type RemoteAuthMode
- type RemoteBranchTracking
- type RemoteConfig
- type Repository
- func InitializeClonedRepository(stateDir string, cfg RemoteConfig, branch string, headCommit string, ...) (*Repository, int, error)
- func InitializeRepository(stateDir string) (*Repository, error)
- func NewSeedRepository() (*Repository, error)
- func NewSeedRepositoryWithMergeState(stateDir string) (*Repository, error)
- func OpenRepository(stateDir string) (*Repository, error)
- func (r *Repository) AbortMergeTransaction(targetBranch, callerTransactionID string) error
- func (r *Repository) AdvanceBranch(branch string) (ObjectID, error)
- func (r *Repository) ApplyCleanBoundMerge(sourceBranch, targetBranch, transactionID string, binding MergePreviewBinding) (ObjectID, error)
- func (r *Repository) ApplyConflictedBoundMerge(sourceBranch, targetBranch, transactionID string, binding MergePreviewBinding) error
- func (r *Repository) ApplyMergePreview(sourceBranch, targetBranch, transactionID string, previewID ObjectID, ...) (ObjectID, error)
- func (r *Repository) BranchStagingStatus(branch string) (BranchStagingStatus, error)
- func (r *Repository) BranchesContaining(selector ContainmentSelector) (BranchContainmentResult, error)
- func (r *Repository) BranchesContainingContext(ctx context.Context, request BranchesContainingRequest) (BranchContainmentResult, error)
- func (r *Repository) BuildPushPack(ctx context.Context, branch, baseCommit string) (PushPack, error)
- func (r *Repository) CherryPick(request CherryPickRequest) (CherryPickResult, error)
- func (r *Repository) Close() error
- func (r *Repository) CommitStagedMutationBatch(request CommitStagedMutationRequest) (CommitStagedMutationResult, error)
- func (r *Repository) CommitStagedMutations(branch string) (CommitStagedMutationResult, error)
- func (r *Repository) CreateBranch(name string, source branch.Source) (branch.CreateResult, error)
- func (r *Repository) DeleteBranch(name string) (branch.DeleteResult, error)
- func (r *Repository) Diff(request DiffRequest) (DiffResult, error)
- func (r *Repository) DiffContext(ctx context.Context, request DiffRequest) (DiffResult, error)
- func (r *Repository) EnsureBranchHeadProjection(branch string, commit *ObjectID) (ProjectionStatus, error)
- func (r *Repository) FilterNodes(request FilterNodesRequest) (FilterNodesResult, error)
- func (r *Repository) FilterNodesContext(ctx context.Context, request FilterNodesRequest) (FilterNodesResult, error)
- func (r *Repository) FinalizeMergeTransaction(targetBranch, callerTransactionID string) (ObjectID, error)
- func (r *Repository) Fsck() (FsckResult, error)
- func (r *Repository) GC(options GCOptions) (GCResult, error)
- func (r *Repository) History(request HistoryRequest) (HistoryResult, error)
- func (r *Repository) HistoryContext(ctx context.Context, request HistoryRequest) (HistoryResult, error)
- func (r *Repository) Impact(request ImpactRequest) (ImpactResult, error)
- func (r *Repository) ImpactContext(ctx context.Context, request ImpactRequest) (ImpactResult, error)
- func (r *Repository) Initialization() (Initialization, error)
- func (r *Repository) InspectMergeTransaction(targetBranch, callerTransactionID string) (MergeTransactionStatus, error)
- func (r *Repository) InstallPullPack(ctx context.Context, branch string, packs [][]byte, expectedHead string) (InstallPullResult, error)
- func (r *Repository) InstallReconciliationPack(ctx context.Context, branch string, packs [][]byte, expectedHead string) (InstallPullResult, error)
- func (r *Repository) ListBranches() (branch.ListResult, error)
- func (r *Repository) OpenAsset(hash string) (io.ReadCloser, int64, error)
- func (r *Repository) PinBranch(name string) (ObjectID, error)
- func (r *Repository) PinBranchContext(ctx context.Context, name string) (ObjectID, error)
- func (r *Repository) PinnedEdges(commitID ObjectID) ([]Edge, error)
- func (r *Repository) PinnedEdgesContext(ctx context.Context, commitID ObjectID) ([]Edge, error)
- func (r *Repository) PinnedNodes(commitID ObjectID) ([]Node, error)
- func (r *Repository) PinnedNodesContext(ctx context.Context, commitID ObjectID) ([]Node, error)
- func (r *Repository) PinnedSnapshotRecord(commitID ObjectID) (PinnedSnapshotRecord, error)
- func (r *Repository) PinnedSnapshotRecordContext(ctx context.Context, commitID ObjectID) (PinnedSnapshotRecord, error)
- func (r *Repository) PreviewMerge(sourceBranch, targetBranch string) (MergePreview, error)
- func (r *Repository) ProjectionStatus() (ProjectionStatus, error)
- func (r *Repository) ProjectionStatusContext(ctx context.Context) (ProjectionStatus, error)
- func (r *Repository) Prune(request PruneRequest) (PruneResult, error)
- func (r *Repository) ReadAsset(ctx context.Context, branch, locatorOrNode string) (io.ReadCloser, int64, AssetMetadata, error)
- func (r *Repository) ReconcileBranch(branch, remoteBranch, author, message string) (ReconcileResult, error)
- func (r *Repository) RecoverMergeTransactions() error
- func (r *Repository) Remote() (RemoteConfig, bool, error)
- func (r *Repository) RemoteBranchTracking(localBranch string) (RemoteBranchTracking, bool, error)
- func (r *Repository) RemoveRemote() error
- func (r *Repository) RepositoryID() string
- func (r *Repository) ResolveAssetNode(branch, nodeID string) (string, AssetMetadata, error)
- func (r *Repository) ResolveConflictedMerge(request ResolveConflictedMergeRequest) error
- func (r *Repository) ResolveExplicitCommit(branch string, requested ObjectID, allowDetached bool) (ObjectID, error)
- func (r *Repository) ResolveExplicitCommitContext(ctx context.Context, branch string, requested ObjectID, allowDetached bool) (ObjectID, error)
- func (r *Repository) ResolveMergeTransaction(targetBranch, callerTransactionID string, stagedSnapshot ObjectID) error
- func (r *Repository) ResolvePinned(commitID ObjectID, nodeID string) (Resolution, error)
- func (r *Repository) ResolvePinnedContext(ctx context.Context, commitID ObjectID, nodeID string) (Resolution, error)
- func (r *Repository) RestageMergeTransaction(targetBranch, callerTransactionID string) error
- func (r *Repository) ScanRetention() (RetentionScan, error)
- func (r *Repository) SearchNodes(request SearchNodesRequest) (SearchNodesResult, error)
- func (r *Repository) SearchNodesContext(ctx context.Context, request SearchNodesRequest) (SearchNodesResult, error)
- func (r *Repository) SetRemote(cfg RemoteConfig) error
- func (r *Repository) SetRemoteBranchTracking(localBranch, remoteBranch, remoteHeadCommit string) error
- func (r *Repository) StageAsset(ctx context.Context, req AssetAddRequest) (AssetAddResult, error)
- func (r *Repository) StageMutationBatch(request StageMutationRequest) (StageMutationResult, error)
- func (r *Repository) StageSchemaMigration(request SchemaMigrationRequest) (StageMutationResult, error)
- func (r *Repository) StageSchemaMigrationBatch(request SchemaMigrationRequest) (StageMutationResult, error)
- func (r *Repository) StateDir() string
- func (r *Repository) SwitchBranch(name string) (branch.SwitchResult, error)
- func (r *Repository) ValidatePinnedSchema(commitID ObjectID) (SchemaValidationResolution, error)
- type Resolution
- type ResolveConflictedMergeRequest
- type RetentionScan
- type SchemaMigrationRequest
- type SchemaSnapshot
- type SchemaValidationError
- type SchemaValidationResolution
- type SchemaViolation
- type SchemaViolationCode
- type SearchNodeMatch
- type SearchNodesRequest
- type SearchNodesResult
- type StageMutationRequest
- type StageMutationResult
- type StagedMutationSet
- type UnsupportedPackVersionError
- type Workspace
- type WorkspaceID
- type WorkspaceManifest
- type WorkspaceMigrationRequiredError
- type WorkspaceName
- type WorkspaceRegistry
Constants ¶
const ( MaxSchemaLabelLength = 128 MaxSchemaPropertyKeyLength = 128 MaxPropertyStringLength = 16 * 1024 MaxPropertyEntries = 256 MaxPropertyAggregateBytes = 64 * 1024 MaxPropertyDepth = 16 BuiltinSchemaVersion = graphcontract.BuiltinSchemaVersion GlobalInvariantAcyclic = graphcontract.GlobalInvariantAcyclic GlobalInvariantNoSelfLoop = graphcontract.GlobalInvariantNoSelfLoop UniversalModifierLabel = graphcontract.UniversalModifierLabel )
const ( PropertyNull = graphcontract.PropertyNull PropertyBool = graphcontract.PropertyBool PropertyInteger = graphcontract.PropertyInteger PropertyFloat = graphcontract.PropertyFloat PropertyString = graphcontract.PropertyString PropertyList = graphcontract.PropertyList PropertyMap = graphcontract.PropertyMap )
const ( // PackMagic identifies an IDG pack stream. PackMagic = graphcontract.PackMagic // PackFormatVersion is the version encoded in every pack header. PackFormatVersion = graphcontract.PackFormatVersion // PackIndexFormatVersion is the version of the sidecar object index. PackIndexFormatVersion = graphcontract.PackIndexFormatVersion // PackManifestFormatVersion is the version of objects/info/packs. PackManifestFormatVersion = graphcontract.PackManifestFormatVersion )
const ( // PushCommitFormatV2 identifies a commit ID derived from the v2 commit // frame, matching Rack's sync.CommitFormatV2. PushCommitFormatV2 uint32 = 2 // PushPackFormatV2 identifies a canonical Rack push pack frame, matching // Rack's sync.PackFormatV2. PushPackFormatV2 uint32 = 2 // PushPackFormatV3 identifies a canonical Rack push pack frame supporting general // DAG commit histories, matching Rack's sync.PackFormatV3. PushPackFormatV3 uint32 = 3 )
Rack push wire-format constants and framing, mirroring the canonical v2 push contract already shipped in the spool-rack repository (internal/server/sync/framing.go and internal/server/review/snapshot.go). This is deliberately duplicated here rather than shared through a module dependency: goal-cli-native-push is scoped to this repository only, and reproducing the wire byte layout is the minimal coupling needed to interoperate with Rack's already-accepted push validation pipeline.
const ( RemoteAuthModeBearer = remote.AuthModeBearer RemoteAuthModeAPIKey = remote.AuthModeAPIKey )
Remote auth modes re-exported from the remote package.
const ( SchemaViolationInvalidNode = graphcontract.SchemaViolationInvalidNode SchemaViolationInvalidEdge = graphcontract.SchemaViolationInvalidEdge SchemaViolationNodeID = graphcontract.SchemaViolationNodeID SchemaViolationEdgeID = graphcontract.SchemaViolationEdgeID SchemaViolationNodeLabel = graphcontract.SchemaViolationNodeLabel SchemaViolationEdgeType = graphcontract.SchemaViolationEdgeType SchemaViolationRequiredProperty = graphcontract.SchemaViolationRequiredProperty SchemaViolationPropertyType = graphcontract.SchemaViolationPropertyType SchemaViolationMissingSource = graphcontract.SchemaViolationMissingSource SchemaViolationMissingTarget = graphcontract.SchemaViolationMissingTarget SchemaViolationSourceLabel = graphcontract.SchemaViolationSourceLabel SchemaViolationTargetLabel = graphcontract.SchemaViolationTargetLabel SchemaViolationSourceCardinalityMin = graphcontract.SchemaViolationSourceCardinalityMin SchemaViolationSourceCardinalityMax = graphcontract.SchemaViolationSourceCardinalityMax SchemaViolationTargetCardinalityMin = graphcontract.SchemaViolationTargetCardinalityMin SchemaViolationTargetCardinalityMax = graphcontract.SchemaViolationTargetCardinalityMax SchemaViolationNaturalKeyUnique = graphcontract.SchemaViolationNaturalKeyUnique SchemaViolationAcyclic = graphcontract.SchemaViolationAcyclic SchemaViolationNoSelfLoop = graphcontract.SchemaViolationNoSelfLoop )
const CurrentWorkspaceManifestVersion = workspace.CurrentManifestVersion
const DefaultGCGracePeriod = defaultGCGracePeriod
DefaultGCGracePeriod is the retention period applied when GCOptions.GracePeriod is zero.
const ( // PackCompressionZstd is the required compression for PackFormatVersion. PackCompressionZstd = graphcontract.PackCompressionZstd )
const SeedNodeID = "11111111-1111-4111-8111-111111111111"
SeedNodeID is the stable identifier of the node in every seeded repository.
Variables ¶
var ( ErrCherryPickCommitRequired = cherrypick.ErrCommitRequired ErrCherryPickTargetBranchRequired = cherrypick.ErrTargetBranchRequired ErrCherryPickConflicts = cherrypick.ErrConflicts )
CherryPick sentinel errors re-exported from the cherrypick package.
var ( // ErrInvalidContinuation reports a continuation token from another request or with invalid encoding. ErrInvalidContinuation = errors.New("diff continuation token does not match request") // ErrInvalidDiffBudget reports a non-positive row budget. ErrInvalidDiffBudget = errors.New("diff max rows must be positive") )
var ( // ErrInvalidContainmentSelector reports a containment selector with an invalid combination of keys. ErrInvalidContainmentSelector = errors.New("containment selector must identify exactly one entity ID, snapshot, or natural key") // ErrEntityHistoryNotFound reports an empty entity identifier or no matching history. ErrEntityHistoryNotFound = errors.New("entity has no history") )
var ( // ErrMissingImpactDelta reports an impact request without hypothetical mutations. ErrMissingImpactDelta = errors.New("impact delta is required") // ErrInvalidImpactBudget reports a negative depth or non-positive visited-node limit. ErrInvalidImpactBudget = errors.New("impact traversal budget is invalid") )
var ( // ErrMergePreviewNotClean reports an attempt to apply a preview with conflicts. ErrMergePreviewNotClean = errors.New("merge preview is not clean") // ErrMergePreviewMismatch reports an apply request that does not name the current preview. ErrMergePreviewMismatch = errors.New("merge preview identifier does not match") )
var ( // ErrInvalidPropertyValue reports a property value rejected by graphcontract. ErrInvalidPropertyValue = graphcontract.ErrInvalidPropertyValue // ErrInvalidSchemaSnapshot reports a schema snapshot without a version. ErrInvalidSchemaSnapshot = graphcontract.ErrInvalidSchemaSnapshot // ErrInvalidSchemaDefinition reports inconsistent or unsupported schema rules. ErrInvalidSchemaDefinition = graphcontract.ErrInvalidSchemaDefinition // ErrInvalidSchemaIdentifier reports a label, type, or property key unsafe for storage. ErrInvalidSchemaIdentifier = graphcontract.ErrInvalidSchemaIdentifier // ErrPropertyValueLimit reports a property value exceeding an ingestion limit. ErrPropertyValueLimit = errors.New("property value exceeds limit") )
var ( // ErrPackCorrupt reports malformed or inconsistent pack, index, or manifest data. ErrPackCorrupt = graphcontract.ErrPackCorrupt // ErrUnsupportedPackVersion reports a pack storage format newer or older than this repository supports. ErrUnsupportedPackVersion = graphcontract.ErrUnsupportedPackVersion // ErrGCCorrupt reports corruption that prevents GC from safely deciding what to retain. ErrGCCorrupt = errors.New("GC cannot continue with corrupt repository data") )
var ( // ErrHistoricalProjectionUnsupported reports a request that cannot be served // by the branch-head-only projection cache. ErrHistoricalProjectionUnsupported = errors.New("historical snapshot projections are unsupported") ErrProjectionUnavailable = errors.New("projection is unavailable") )
var ( ErrProtectedBranch = prune.ErrProtectedBranch ErrUncommittedStagedChanges = prune.ErrUncommittedStagedChanges )
Pruning errors re-exported from the prune package.
var ( // ErrPullBaseMismatch reports that the pack's declared base commit does // not match the branch's locally recomputed wire head, so the pack // cannot be installed as a fast-forward extension of local history. ErrPullBaseMismatch = errors.New("repository: pull pack base does not match local branch head") // ErrPullBootstrapUnsupported reports that the pack declares an empty // base (a from-scratch history with no common ancestor). Installing a // branch with no local ancestry in common with Rack is not yet // supported; that is a separate, not-yet-implemented capability. ErrPullBootstrapUnsupported = errors.New("repository: pull does not yet support bootstrapping a branch with no local history") // ErrPullInvalidPack reports that a pull pack failed to decode or // failed an internal consistency check (canonical round-trip, object // content hash, or final head mismatch). ErrPullInvalidPack = errors.New("repository: invalid pull pack") // ErrPullChainDiscontinuous reports that a pack's declared base does not // chain from the previous pack's target within a single pull. ErrPullChainDiscontinuous = errors.New("repository: pull packs are not contiguous") )
Pull errors.
var ( // ErrNothingToPush reports that the branch head is already the given // base commit, so there is no new history to publish. ErrNothingToPush = errors.New("repository: nothing to push") // ErrPushBaseNotFound reports that the given base commit does not name // any commit in the branch's local DAG history, so the CLI // cannot determine which local commits are new. ErrPushBaseNotFound = errors.New("repository: push base commit not found in local branch history") )
Push errors.
var ( // ErrInvalidListBudget reports a negative row or response-byte limit. ErrInvalidListBudget = errors.New("list query budget is invalid") // ErrResponseBudgetTooSmall reports a byte budget unable to represent a result. // The limit applies to the repository payload only; public adapters must reserve // space for their envelopes before invoking repository queries. ErrResponseBudgetTooSmall = errors.New("response budget cannot represent result") )
var ( ErrRemoteInvalidConfig = remote.ErrInvalidConfig ErrRemoteSecretLikeValue = remote.ErrSecretLikeValue )
Remote sentinel errors re-exported from the remote package.
var ( // ErrRepositoryNotInitialized reports an attempt to open repository state that does not exist. ErrRepositoryNotInitialized = errors.New("repository is not initialized") // ErrRepositoryAlreadyInitialized reports an attempt to initialize existing repository state. ErrRepositoryAlreadyInitialized = errors.New("repository is already initialized") // ErrLegacyRepositoryState reports an unsupported monolithic repository.json state file. ErrLegacyRepositoryState = errors.New("legacy repository.json state is unsupported") // ErrBranchNotFound reports a requested branch that is absent from the repository. ErrBranchNotFound = branch.ErrNotFound // ErrBranchRequired reports a missing branch selector. ErrBranchRequired = branch.ErrRequired // ErrBranchMissingSource reports a branch creation source with neither branch nor commit. ErrBranchMissingSource = branch.ErrMissingSource // ErrBranchAmbiguousSource reports a source that names both a branch and commit. ErrBranchAmbiguousSource = branch.ErrAmbiguousSource // ErrBranchSourceNotFound reports a requested branch-creation source that does not exist. ErrBranchSourceNotFound = branch.ErrSourceNotFound // ErrBranchAlreadyExists reports an attempt to create an existing branch. ErrBranchAlreadyExists = branch.ErrAlreadyExists // ErrDefaultBranchProtected reports an attempt to delete the default branch. ErrDefaultBranchProtected = branch.ErrDefaultProtected // ErrActiveBranchProtected reports an attempt to delete the active branch. ErrActiveBranchProtected = branch.ErrActiveProtected // ErrCommitNotFound reports a requested commit that is absent from the repository. ErrCommitNotFound = errors.New("commit not found") // ErrCommitNotReachable reports a commit that is not reachable from its selected branch. ErrCommitNotReachable = errors.New("commit is not reachable from branch") // ErrNodeNotFound reports a node that is absent from the selected snapshot. ErrNodeNotFound = errors.New("node not found in snapshot") // ErrMissingMergePreviewBinding reports an incomplete merge preview binding. ErrMissingMergePreviewBinding = errors.New("merge preview binding is required") // ErrMissingMergeTransactionID reports an empty merge transaction identifier. ErrMissingMergeTransactionID = errors.New("merge transaction ID is required") // ErrStaleMergePreview reports a preview whose branches or merge base have changed. ErrStaleMergePreview = errors.New("merge preview binding is stale") // ErrMergeConflicted reports that a merge transaction was recorded for manual resolution. ErrMergeConflicted = errors.New("merge preview contains conflicts") // ErrMergeLeaseHeldByOther reports a merge target leased by another transaction. ErrMergeLeaseHeldByOther = errors.New("merge transaction lease is held by another transaction") // ErrMergeOperationNotOwner reports an operation attempted by a non-owning transaction. ErrMergeOperationNotOwner = errors.New("merge operation is not owned by this transaction") // ErrMergeNotInProgress reports an operation for a missing merge transaction. ErrMergeNotInProgress = errors.New("merge transaction is not in progress") // ErrMergeResolutionIncomplete reports finalization before resolution and restaging complete. ErrMergeResolutionIncomplete = errors.New("merge transaction resolution is incomplete") // ErrMergeStagedSnapshotMissing reports a resolution snapshot absent from repository state. ErrMergeStagedSnapshotMissing = errors.New("merge staged snapshot was not found") // ErrMergeTargetLeaseHeld reports an operation blocked by an active target merge transaction. ErrMergeTargetLeaseHeld = errors.New("merge target branch has an active transaction") // ErrMergeResolutionSelection reports malformed, incomplete, or unknown conflict choices. ErrMergeResolutionSelection = errors.New("merge resolution selections are invalid") // ErrMergeResolutionPreviewMismatch reports a resolution request for another preview. ErrMergeResolutionPreviewMismatch = errors.New("merge resolution preview identifier does not match") // ErrMergeRepositoryLocked reports repository state locked by another process. ErrMergeRepositoryLocked = errors.New("merge repository is locked by another process") // ErrMergeRepositoryClosed reports use after Close. ErrMergeRepositoryClosed = errors.New("merge repository is closed") // ErrAssetNotFound reports an asset blob missing from storage. ErrAssetNotFound = asset.ErrAssetNotFound // ErrInvalidAssetURI reports a malformed or unsupported asset locator URI. ErrInvalidAssetURI = asset.ErrInvalidAssetURI // ErrInvalidAssetHash reports an invalid BLAKE3 asset hash. ErrInvalidAssetHash = asset.ErrInvalidAssetHash // ErrCorruptAsset reports an asset blob that does not match its expected checksum. ErrCorruptAsset = asset.ErrCorruptAsset )
var ( // ErrInvalidProjectionSearch reports an empty or malformed lexical query. ErrInvalidProjectionSearch = errors.New("projection search query is invalid") // ErrInvalidMetadataPredicate reports a predicate with incompatible operands. ErrInvalidMetadataPredicate = errors.New("metadata predicate is invalid") // ErrUnindexedMetadataProperty reports a predicate for a property not indexed // by the selected snapshot schema. ErrUnindexedMetadataProperty = errors.New("metadata property is not indexed") // ErrUnsupportedMetadataPredicate reports a predicate whose value type is not // permitted by the selected snapshot schema. ErrUnsupportedMetadataPredicate = errors.New("metadata predicate is unsupported") )
var ( // ErrInvalidMutationBatch reports an empty, duplicate, malformed, or inapplicable mutation batch. ErrInvalidMutationBatch = errors.New("mutation batch is invalid") // ErrMissingEdgeEndpoint reports a mutation that leaves an edge without existing endpoints. ErrMissingEdgeEndpoint = errors.New("edge endpoint is missing") // ErrNoStagedMutations reports a commit request for a branch without staged changes. ErrNoStagedMutations = errors.New("branch has no staged mutations") // ErrStaleStagedBase reports staged mutations whose branch head has moved. ErrStaleStagedBase = errors.New("staged mutation base is stale") )
var ( ErrWorkspaceNotRegistered = workspace.ErrWorkspaceNotRegistered ErrWorkspaceExists = workspace.ErrWorkspaceExists ErrWorkspaceInvalidRegistry = workspace.ErrInvalidRegistry ErrWorkspaceInvalidName = workspace.ErrInvalidName ErrWorkspaceInvalidID = workspace.ErrInvalidID ErrWorkspaceInvalidStorageRoot = workspace.ErrInvalidStorageRoot ErrWorkspaceManifestNotFound = workspace.ErrManifestNotFound ErrWorkspaceInvalidManifest = workspace.ErrInvalidManifest ErrWorkspaceManifestConflict = workspace.ErrManifestConflict ErrWorkspaceInvalidRepositoryID = workspace.ErrInvalidRepositoryID )
Workspace sentinel errors re-exported from the workspace package.
var ErrFsckCorrupt = errors.New("repository integrity check failed")
ErrFsckCorrupt reports that Fsck found one or more integrity violations.
var ErrInvalidRemoteBranchTracking = errors.New("remote branch tracking entry is invalid")
ErrInvalidRemoteBranchTracking reports that a caller attempted to record remote-branch tracking metadata with an invalid local branch name, remote branch name, or head commit. Persisting an invalid entry would make the repository fail to reopen (loadControlState rejects invalid entries), so SetRemoteBranchTracking validates before ever touching durable state.
var ErrInvalidSchemaTOML = graphcontract.ErrInvalidSchemaTOML
var ErrRemoteNotConfigured = errors.New("repository has no configured remote")
ErrRemoteNotConfigured reports that the repository has no configured remote.
var ErrSchemaValidation = graphcontract.ErrSchemaValidation
Functions ¶
func FindWorkspaceByID ¶ added in v0.0.8
func FindWorkspaceByID(root string, id WorkspaceID) (string, error)
FindWorkspaceByID resolves detached state from its immutable identity.
func MigrateRepositoryFormatV1ToV2 ¶ added in v1.6.0
MigrateRepositoryFormatV1ToV2 upgrades a format_version 1 Spool repository to format_version 2.
func ReconciliationBranchName ¶ added in v1.5.0
ReconciliationBranchName returns the deterministic local branch name used to mirror a remote branch's complete current history during non-fast-forward push reconciliation (see spl push --reconcile). It is a plain naming convention, not itself durable state: the branch is (re)created fresh by InstallReconciliationPack on every reconciliation attempt.
func RepositoryWorkspacePath ¶ added in v0.0.7
func RepositoryWorkspacePath(root string, id WorkspaceID) (string, error)
func UpdateWorkspaceRegistry ¶ added in v0.0.7
func UpdateWorkspaceRegistry(root string, update func(*WorkspaceRegistry) error) error
func ValidateSchemaSnapshot ¶
func WorkspaceStorageRoot ¶ added in v0.0.7
WorkspaceStorageRoot returns the platform-specific data directory.
func WriteWorkspaceManifest ¶ added in v0.0.8
func WriteWorkspaceManifest(repositoryRoot string, manifest WorkspaceManifest) error
WriteWorkspaceManifest atomically writes a checkout-owned workspace manifest.
Types ¶
type AssetAddRequest ¶ added in v1.8.0
type AssetAddRequest = asset.AddRequest
Asset types re-exported from the asset subpackage.
type AssetAddResult ¶ added in v1.8.0
Asset types re-exported from the asset subpackage.
type AssetMetadata ¶ added in v1.8.0
Asset types re-exported from the asset subpackage.
type AssetStore ¶ added in v1.8.0
Asset types re-exported from the asset subpackage.
type BranchContainmentResult ¶
type BranchContainmentResult struct {
// Branches contains matching branch names in lexical order.
Branches []string `json:"branches"`
// ContinuationToken resumes remaining branches with the same request.
ContinuationToken string `json:"continuationToken,omitempty"`
}
BranchContainmentResult lists lexically ordered branches matching a containment selector.
type BranchCreateRequest ¶ added in v0.0.7
type BranchCreateRequest = branch.CreateRequest
Branch types re-exported from the branch subpackage.
type BranchCreateResult ¶ added in v0.0.7
type BranchCreateResult = branch.CreateResult
Branch types re-exported from the branch subpackage.
type BranchDeleteRequest ¶ added in v0.0.7
type BranchDeleteRequest = branch.DeleteRequest
Branch types re-exported from the branch subpackage.
type BranchDeleteResult ¶ added in v0.0.7
type BranchDeleteResult = branch.DeleteResult
Branch types re-exported from the branch subpackage.
type BranchListResult ¶ added in v0.0.7
type BranchListResult = branch.ListResult
Branch types re-exported from the branch subpackage.
type BranchSource ¶ added in v0.0.7
Branch types re-exported from the branch subpackage.
type BranchStagingStatus ¶
type BranchStagingStatus struct {
// Branch identifies the requested branch.
Branch string `json:"branch"`
// BaseCommit is the staged base commit, when changes exist.
BaseCommit ObjectID `json:"baseCommit,omitempty"`
// Operations is the current number of shared staged operations.
Operations int `json:"operations"`
}
BranchStagingStatus describes the shared staged mutation delta for a branch.
type BranchSwitchRequest ¶ added in v0.0.7
type BranchSwitchRequest = branch.SwitchRequest
Branch types re-exported from the branch subpackage.
type BranchSwitchResult ¶ added in v0.0.7
type BranchSwitchResult = branch.SwitchResult
Branch types re-exported from the branch subpackage.
type BranchesContainingRequest ¶
type BranchesContainingRequest struct {
// Selector identifies the entity or snapshot to find.
Selector ContainmentSelector `json:"selector"`
// MaxRows limits branch names in one page. It must be positive.
MaxRows int `json:"maxRows"`
// MaxResponseBytes limits the JSON-encoded repository result. It must be positive.
MaxResponseBytes int `json:"maxResponseBytes"`
// ContinuationToken resumes a matching containment query.
ContinuationToken string `json:"continuationToken,omitempty"`
}
BranchesContainingRequest describes a bounded containment query. The response byte limit applies to BranchContainmentResult, so public adapters can reserve their own envelope overhead before calling BranchesContainingContext.
type Cardinality ¶
type Cardinality = graphcontract.Cardinality
type CherryPickChange ¶ added in v1.2.0
type CherryPickChange = cherrypick.Change
CherryPickChange describes an entity changed by a cherry-pick.
type CherryPickCommittedWithWarningError ¶ added in v1.2.0
type CherryPickCommittedWithWarningError struct {
Result CherryPickResult
// contains filtered or unexported fields
}
CherryPickCommittedWithWarningError reports that a cherry-pick operation was committed, but directory synchronization or projection update had a durability warning.
func (*CherryPickCommittedWithWarningError) Error ¶ added in v1.2.0
func (e *CherryPickCommittedWithWarningError) Error() string
Error returns the underlying durability warning.
func (*CherryPickCommittedWithWarningError) Unwrap ¶ added in v1.2.0
func (e *CherryPickCommittedWithWarningError) Unwrap() error
Unwrap returns the underlying durability warning.
type CherryPickConflict ¶ added in v1.2.0
type CherryPickConflict = cherrypick.Conflict
CherryPickConflict describes a deterministic three-way merge disagreement during cherry-picking.
type CherryPickRequest ¶ added in v1.2.0
type CherryPickRequest = cherrypick.Request
CherryPickRequest describes the options for a cherry-pick transplantation operation.
type CherryPickResult ¶ added in v1.2.0
type CherryPickResult = cherrypick.Result
CherryPickResult summarizes the transplanted changes, resulting commit, conflicts, and schema violations.
type CherryPickSchemaViolation ¶ added in v1.2.0
type CherryPickSchemaViolation = cherrypick.SchemaViolation
CherryPickSchemaViolation describes a schema rule or constraint failure during cherry-picking.
type CommitStagedMutationRequest ¶
type CommitStagedMutationRequest struct {
// Branch identifies the branch whose staged changes are committed.
Branch string `json:"branch"`
// Author optionally overrides the default commit author.
Author string `json:"author,omitempty"`
// Message optionally overrides the default commit message.
Message string `json:"message,omitempty"`
}
CommitStagedMutationRequest describes the caller-provided metadata for a staged commit.
type CommitStagedMutationResult ¶
type CommitStagedMutationResult struct {
// Branch identifies the branch advanced by the commit.
Branch string `json:"branch"`
// Commit identifies the newly materialized commit.
Commit ObjectID `json:"commit"`
}
CommitStagedMutationResult identifies the new commit created from a branch's staged mutations.
type CommittedWithWarningError ¶
type CommittedWithWarningError struct {
// Result identifies the commit that succeeded before final directory synchronization failed.
Result CommitStagedMutationResult
// contains filtered or unexported fields
}
CommittedWithWarningError reports that a durable state write completed but its final sync failed.
func (*CommittedWithWarningError) Error ¶
func (e *CommittedWithWarningError) Error() string
Error returns the underlying durability warning.
func (*CommittedWithWarningError) Unwrap ¶
func (e *CommittedWithWarningError) Unwrap() error
Unwrap returns the underlying durability warning.
type ContainmentSelector ¶
type ContainmentSelector struct {
// EntityID selects branches with commits affecting this node or edge.
EntityID string `json:"entityId,omitempty"`
// SnapshotID selects branches whose ancestry contains this snapshot.
SnapshotID ObjectID `json:"snapshotId,omitempty"`
// NaturalKey is reserved for a natural-key selector.
NaturalKey string `json:"naturalKey,omitempty"`
}
ContainmentSelector identifies the entity or snapshot for branch containment lookup.
type DiffContext ¶
type DiffContext struct {
// Entity is "node" or "edge".
Entity string `json:"entity"`
// ID identifies the context entity.
ID string `json:"id"`
// Node is populated for node context.
Node *Node `json:"node,omitempty"`
// Edge is populated for edge context.
Edge *Edge `json:"edge,omitempty"`
}
DiffContext describes an unchanged entity included as one-hop context.
type DiffEntry ¶
type DiffEntry struct {
// Entity is "node" or "edge".
Entity string `json:"entity"`
// Change is "added", "removed", or "modified".
Change string `json:"change"`
// ID identifies the changed entity.
ID string `json:"id"`
// Node is populated when Entity is "node".
Node *Node `json:"node,omitempty"`
// Edge is populated when Entity is "edge".
Edge *Edge `json:"edge,omitempty"`
}
DiffEntry describes an added, removed, or modified graph entity.
type DiffFilter ¶
type DiffFilter struct {
// NodeIDs restricts returned node changes when non-empty.
NodeIDs []string `json:"nodeIds,omitempty"`
// EdgeIDs restricts returned edge changes when non-empty.
EdgeIDs []string `json:"edgeIds,omitempty"`
// NodeTitleSubstr restricts node changes to titles containing this substring.
NodeTitleSubstr string `json:"nodeTitleSubstring,omitempty"`
}
DiffFilter restricts diff changes by identifiers or node title substring.
type DiffRequest ¶
type DiffRequest struct {
// Base identifies the already pinned older comparison commit.
Base ObjectID `json:"base"`
// Target identifies the already pinned newer comparison commit.
Target ObjectID `json:"target"`
// Filter optionally limits the returned changes.
Filter DiffFilter `json:"filter,omitempty"`
// MaxRows limits changes and context entries returned in this page.
MaxRows int `json:"maxRows"`
// MaxResponseBytes limits the JSON-encoded response size.
MaxResponseBytes int `json:"maxResponseBytes"`
// IncludeOneHop includes related unchanged nodes and edges within remaining budgets.
IncludeOneHop bool `json:"includeOneHop,omitempty"`
// ContinuationToken resumes a prior request with matching comparison and budgets.
ContinuationToken string `json:"continuationToken,omitempty"`
}
DiffRequest describes a bounded, optionally filtered comparison of two snapshots.
type DiffResult ¶
type DiffResult struct {
// BaseCommit is the resolved commit selected by Base.
BaseCommit ObjectID `json:"baseCommit"`
// TargetCommit is the resolved commit selected by Target.
TargetCommit ObjectID `json:"targetCommit"`
// Changes contains the ordered page of matching changes.
Changes []DiffEntry `json:"changes"`
// Context contains related unchanged entities when requested and budget permits.
Context []DiffContext `json:"context,omitempty"`
// ContinuationToken resumes remaining changes with the same request.
ContinuationToken string `json:"continuationToken,omitempty"`
// ContextTruncated reports that requested one-hop context exceeded a page budget.
ContextTruncated bool `json:"contextTruncated,omitempty"`
}
DiffResult is one bounded page of changes and optional related context.
type Edge ¶
type Edge = graphcontract.Edge
type EdgeTypeRule ¶
type EdgeTypeRule = graphcontract.EdgeTypeRule
type FilterNodesRequest ¶
type FilterNodesRequest struct {
Branch string `json:"branch"`
Commit ObjectID `json:"commit"`
Labels []string `json:"labels,omitempty"`
Predicates []MetadataPredicate `json:"predicates,omitempty"`
MaxRows int `json:"maxRows"`
MaxResponseBytes int `json:"maxResponseBytes"`
ContinuationToken string `json:"continuationToken,omitempty"`
}
FilterNodesRequest describes a bounded metadata query of the branch-head projection. Labels and predicates are combined with AND.
type FilterNodesResult ¶
type FilterNodesResult struct {
Branch string `json:"branch"`
Commit ObjectID `json:"commit"`
Snapshot ObjectID `json:"snapshot"`
Nodes []Node `json:"nodes"`
ContinuationToken string `json:"continuationToken,omitempty"`
}
FilterNodesResult is one deterministic page of metadata matches.
type FsckDiagnostic ¶
type FsckDiagnostic struct {
Code string `json:"code"`
Path string `json:"path,omitempty"`
Branch string `json:"branch,omitempty"`
Object ObjectID `json:"object,omitempty"`
Detail string `json:"detail"`
}
FsckDiagnostic describes one deterministic integrity or maintenance finding.
type FsckError ¶
type FsckError struct {
Result FsckResult
}
FsckError carries the structured report for a corrupt repository.
type FsckResult ¶
type FsckResult struct {
Valid bool `json:"valid"`
Branches []string `json:"branches"`
Commits int `json:"commits"`
Snapshots int `json:"snapshots"`
Objects int `json:"objects"`
Diagnostics []FsckDiagnostic `json:"diagnostics"`
Informational []FsckDiagnostic `json:"informational,omitempty"`
}
FsckResult is the complete report produced by an integrity check.
func FsckRepository ¶
func FsckRepository(stateDir string) (FsckResult, error)
FsckRepository traverses every durable branch reference and checks the reachable immutable objects and mutable control state without repairing it.
type GCCommittedWithWarningError ¶
GCCommittedWithWarningError reports cleanup that failed after a replacement pack generation was durably published. Result remains authoritative.
func (*GCCommittedWithWarningError) Error ¶
func (e *GCCommittedWithWarningError) Error() string
Error implements error.
func (*GCCommittedWithWarningError) Unwrap ¶
func (e *GCCommittedWithWarningError) Unwrap() error
Unwrap returns the cleanup warning.
type GCOptions ¶
type GCOptions struct {
// DryRun reports planned work without publishing a pack or deleting loose objects.
DryRun bool
// Repack compacts active packs and reachable loose objects into one replacement generation.
Repack bool
// GracePeriod overrides the retention period for unreachable loose objects.
// A zero value uses DefaultGCGracePeriod.
GracePeriod time.Duration
}
GCOptions configures explicit object-store maintenance.
type GCResult ¶
type GCResult struct {
Roots uint64 `json:"roots"`
ReachableObjects uint64 `json:"reachableObjects"`
PackedObjects uint64 `json:"packedObjects"`
RetainedUnreachableObjects uint64 `json:"retainedUnreachableObjects"`
PrunedLooseObjects uint64 `json:"prunedLooseObjects"`
RetiredPacks uint64 `json:"retiredPacks"`
ReclaimedBytes uint64 `json:"reclaimedBytes"`
}
GCResult is the complete, machine-readable report from one GC attempt.
type GlobalInvariant ¶
type GlobalInvariant = graphcontract.GlobalInvariant
type GraphSnapshot ¶
type GraphSnapshot = graphcontract.Snapshot
GraphSnapshot is the repository's compatibility alias for the public canonical graph contract snapshot root, the immutable content-addressed root set for one graph version.
type HistoryEntry ¶
type HistoryEntry struct {
// Commit identifies the affecting commit.
Commit ObjectID `json:"commit"`
// BeforeSnapshot identifies the first-parent snapshot before the commit, when present.
BeforeSnapshot ObjectID `json:"beforeSnapshot,omitempty"`
// AfterSnapshot identifies the snapshot created by the commit.
AfterSnapshot ObjectID `json:"afterSnapshot"`
// ChangedFields names node fields changed by the commit.
ChangedFields []string `json:"changedFields,omitempty"`
// EdgeAdditions contains relevant added or updated edge values.
EdgeAdditions []Edge `json:"edgeAdditions,omitempty"`
// EdgeRemovals contains relevant removed or replaced edge values.
EdgeRemovals []Edge `json:"edgeRemovals,omitempty"`
// Author is the commit author.
Author string `json:"author"`
// Time is the UTC time recorded for the commit.
Time time.Time `json:"time"`
// Message is the commit message.
Message string `json:"message"`
}
HistoryEntry describes one commit that affected the requested entity.
type HistoryRequest ¶
type HistoryRequest struct {
// Commit identifies the traversal starting commit.
Commit ObjectID `json:"commit"`
// EntityID identifies the node or edge whose changes are returned.
EntityID string `json:"entityId"`
// AllParents includes all parent links rather than only each commit's first parent.
AllParents bool `json:"allParents,omitempty"`
// MaxRows limits entries in one page. Zero preserves the legacy unbounded read.
MaxRows int `json:"maxRows,omitempty"`
// MaxResponseBytes limits the JSON-encoded HistoryResult payload. Zero preserves
// the legacy unbounded read; adapters must reserve their envelope overhead.
MaxResponseBytes int `json:"maxResponseBytes,omitempty"`
// ContinuationToken resumes a matching paged history request.
ContinuationToken string `json:"continuationToken,omitempty"`
}
HistoryRequest selects an entity's commit history from an already pinned commit.
type HistoryResult ¶
type HistoryResult struct {
// Entries contains the matching history entries.
Entries []HistoryEntry `json:"entries"`
// ContinuationToken resumes remaining entries with the same request.
ContinuationToken string `json:"continuationToken,omitempty"`
}
HistoryResult contains commits affecting the requested entity in traversal order.
type ImpactEntry ¶
type ImpactEntry struct {
// Node is the impacted node.
Node Node `json:"node"`
// Path is a canonical path from a changed seed node to Node.
Path []string `json:"path"`
// Distance is the number of edges in Path.
Distance int `json:"distance"`
}
ImpactEntry identifies an impacted node and its canonical supporting path.
type ImpactRequest ¶
type ImpactRequest struct {
// Commit identifies the already pinned snapshot to analyze.
Commit ObjectID `json:"commit"`
// Delta contains validated hypothetical mutations that are never persisted.
Delta []MutationOperation `json:"delta"`
// MaxDepth limits outgoing dependency traversal distance.
MaxDepth int `json:"maxDepth"`
// MaxVisited limits nodes traversed and returned.
MaxVisited int `json:"maxVisited"`
// MaxRows limits impacts in one page. Zero returns up to MaxVisited, preserving
// legacy behavior.
MaxRows int `json:"maxRows,omitempty"`
// MaxResponseBytes limits the JSON-encoded ImpactResult payload. Zero preserves
// legacy unbounded behavior; adapters must reserve envelope overhead.
MaxResponseBytes int `json:"maxResponseBytes,omitempty"`
// ContinuationToken resumes a matching impact query.
ContinuationToken string `json:"continuationToken,omitempty"`
}
ImpactRequest describes a hypothetical, non-persistent graph change and the snapshot against which it is analyzed.
type ImpactResult ¶
type ImpactResult struct {
// Commit identifies the selected commit.
Commit ObjectID `json:"commit"`
// Snapshot identifies the selected graph snapshot.
Snapshot ObjectID `json:"snapshot"`
// Impacts contains canonically ordered impacted nodes.
Impacts []ImpactEntry `json:"impacts"`
// ContinuationToken resumes remaining impacts with the same request.
ContinuationToken string `json:"continuationToken,omitempty"`
// CapacityExhausted reports that MaxVisited prevented further traversal.
CapacityExhausted bool `json:"capacityExhausted,omitempty"`
}
ImpactResult describes the snapshot analyzed and its bounded impacted nodes.
type Initialization ¶
type Initialization struct {
// DefaultBranch is the branch that cannot be deleted.
DefaultBranch string `json:"defaultBranch"`
// ActiveBranch is the branch currently selected for repository operations.
ActiveBranch string `json:"activeBranch"`
}
Initialization identifies the repository's default and currently active branches.
type InstallPullResult ¶ added in v1.5.0
type InstallPullResult struct {
// Branch is the branch the pull advanced.
Branch string
// CommitsInstalled is the number of new local commits created.
CommitsInstalled int
// HeadCommit is the branch's new local head object ID.
HeadCommit ObjectID
}
InstallPullResult reports the outcome of installing a pull pack.
type MergeChange ¶
type MergeChange = graphcontract.MergeChange
MergeChange describes an entity changed from the target snapshot by a preview.
type MergeConflict ¶
type MergeConflict = graphcontract.MergeConflict
MergeConflict describes a deterministic three-way merge disagreement.
type MergePreview ¶
type MergePreview struct {
ID ObjectID `json:"id"`
Binding MergePreviewBinding `json:"binding"`
SourceBranch string `json:"sourceBranch"`
TargetBranch string `json:"targetBranch"`
Clean bool `json:"clean"`
Changes []MergeChange `json:"changes"`
Conflicts []MergeConflict `json:"conflicts"`
Violations []SchemaViolation `json:"violations,omitempty"`
}
MergePreview is an immutable, deterministic prediction of merging SourceBranch into TargetBranch.
type MergePreviewBinding ¶
type MergePreviewBinding struct {
// MergeBase is the common ancestor used to produce the preview.
MergeBase ObjectID
// SourceCommit is the source branch head inspected by the preview.
SourceCommit ObjectID
// TargetCommit is the target branch head inspected by the preview.
TargetCommit ObjectID
}
MergePreviewBinding pins the commits and merge base inspected by a merge preview.
type MergeResolutionSelection ¶
type MergeResolutionSelection struct {
ConflictID string `json:"conflictId"`
Choice string `json:"choice"`
}
MergeResolutionSelection selects one side for a reported structural or schema conflict.
type MergeTransactionStatus ¶
type MergeTransactionStatus struct {
Preview MergePreview `json:"preview"`
Resolved bool `json:"resolved"`
Restaged bool `json:"restaged"`
}
MergeTransactionStatus is the owner-gated public view of a conflicted merge.
type MetadataPredicate ¶
type MetadataPredicate struct {
Key string `json:"key"`
TextEquals *string `json:"textEquals,omitempty"`
NumberEquals *float64 `json:"numberEquals,omitempty"`
NumberMin *float64 `json:"numberMin,omitempty"`
NumberMax *float64 `json:"numberMax,omitempty"`
}
MetadataPredicate is a typed predicate over one schema-indexed scalar property. Set TextEquals for text equality, NumberEquals for numeric equality, or NumberMin and/or NumberMax for an inclusive numeric range.
type MigrationResult ¶ added in v1.6.0
type MigrationResult struct {
FromVersion int `json:"fromVersion"`
ToVersion int `json:"toVersion"`
BackupPath string `json:"backupPath"`
}
MigrationResult describes the outcome of an explicit repository format migration.
func MigrateRepositoryFormat ¶ added in v1.6.0
func MigrateRepositoryFormat(stateDir string, from, to int) (*MigrationResult, error)
MigrateRepositoryFormat upgrades a Spool repository from format_version 'from' to format_version 'to'. It validates the migration path, acquires the repository lock, creates a durable backup, canonicalizes the commit DAG, remaps refs and reflogs, updates config.toml, invalidates cached projections, and verifies integrity.
type MutationOperation ¶
type MutationOperation struct {
// Action is "add", "update", or "delete".
Action string `json:"action"`
// Entity is "node" or "edge".
Entity string `json:"entity"`
// ID identifies the node or edge to change.
ID string `json:"id"`
// Title supplies the title for added or updated nodes.
Title string `json:"title,omitempty"`
// Source supplies the source node for added or updated edges.
Source string `json:"source,omitempty"`
// Target supplies the target node for added or updated edges.
Target string `json:"target,omitempty"`
// Labels supplies the labels for added or updated nodes.
Labels []string `json:"labels"`
// Type supplies the relationship type for added or updated edges.
Type string `json:"type,omitempty"`
// Properties supplies typed properties for added or updated nodes and edges.
Properties map[string]PropertyValue `json:"properties"`
}
MutationOperation is one requested graph change in a staged batch.
func (MutationOperation) Normalize ¶
func (o MutationOperation) Normalize() (MutationOperation, error)
Normalize returns the canonical representation of an operation's enriched node or edge fields while preserving its compatibility fields.
type Node ¶
type Node = graphcontract.Node
type NodeLabelRule ¶
type NodeLabelRule = graphcontract.NodeLabelRule
type ObjectID ¶
type ObjectID = graphcontract.ObjectID
ObjectID is the content-derived identifier of a durable repository object.
func ObjectIDForEncoded ¶ added in v1.6.0
ObjectIDForEncoded computes the deterministic Blake3 content identifier for an object type and payload.
type PackCompression ¶
type PackCompression = graphcontract.PackCompression
PackCompression identifies the compression applied to a packed object envelope.
type PackCorruptionError ¶
type PackCorruptionError = graphcontract.PackCorruptionError
PackCorruptionError identifies a failed pack, index, or manifest validation.
type PackID ¶
type PackID = graphcontract.PackID
PackID identifies one immutable pack and its paired index.
type PackIndexEntry ¶
type PackIndexEntry = graphcontract.PackIndexEntry
PackIndexEntry maps one object ID to its zstd-compressed canonical loose envelope in a pack. CRC32 is the IEEE CRC32 of the compressed bytes.
type PackManifest ¶
type PackManifest = graphcontract.PackManifest
PackManifest is the atomically replaced list of active packs.
type PackMetadata ¶
type PackMetadata = graphcontract.PackMetadata
PackMetadata identifies an active pack listed by a manifest.
type PerformancePhase ¶ added in v0.0.5
type PerformancePhase struct {
Name string `json:"name"`
Duration time.Duration `json:"-"`
DurationNanos int64 `json:"durationNanos"`
AllocBytes uint64 `json:"allocBytes"`
AllocObjects uint64 `json:"allocObjects"`
HeapAllocBytes uint64 `json:"heapAllocBytes"`
}
PerformancePhase reports one accumulated opt-in diagnostic phase.
type PerformanceRecorder ¶ added in v0.0.5
type PerformanceRecorder struct {
// contains filtered or unexported fields
}
PerformanceRecorder collects opt-in lifecycle diagnostics for tests and benchmarks.
func NewPerformanceRecorder ¶ added in v0.0.5
func NewPerformanceRecorder() *PerformanceRecorder
NewPerformanceRecorder creates an empty recorder.
func (*PerformanceRecorder) Measure ¶ added in v0.0.5
func (r *PerformanceRecorder) Measure(name string) func()
Measure records duration and Go runtime allocation deltas until the returned function is called.
func (*PerformanceRecorder) Phases ¶ added in v0.0.5
func (r *PerformanceRecorder) Phases() []PerformancePhase
Phases returns the recorded phases in a stable order.
type PinnedSnapshotRecord ¶
type PinnedSnapshotRecord struct {
// Commit identifies the pinned commit.
Commit ObjectID
// Snapshot identifies the graph snapshot selected by Commit.
Snapshot ObjectID
// NodeRoot identifies the snapshot's node projection root.
NodeRoot ObjectID
}
PinnedSnapshotRecord identifies the immutable roots for a pinned commit.
type ProjectionStatus ¶
type ProjectionStatus struct {
SchemaVersion int `json:"schemaVersion"`
State string `json:"state"`
Branch string `json:"branch"`
Commit ObjectID `json:"commit"`
NodeRoot ObjectID `json:"nodeRoot"`
}
ProjectionStatus describes the private SQLite projection used by future read surfaces.
type PropertyKind ¶
type PropertyKind = graphcontract.PropertyKind
type PropertyRule ¶
type PropertyRule = graphcontract.PropertyRule
type PropertyValue ¶
type PropertyValue = graphcontract.PropertyValue
func BoolPropertyValue ¶
func BoolPropertyValue(value bool) PropertyValue
func FloatPropertyValue ¶
func FloatPropertyValue(value float64) PropertyValue
func IntegerPropertyValue ¶
func IntegerPropertyValue(value int64) PropertyValue
func ListPropertyValue ¶
func ListPropertyValue(value []PropertyValue) PropertyValue
func MapPropertyValue ¶
func MapPropertyValue(value map[string]PropertyValue) PropertyValue
func NullPropertyValue ¶
func NullPropertyValue() PropertyValue
func StringPropertyValue ¶
func StringPropertyValue(value string) PropertyValue
type PropertyValueKind ¶
type PropertyValueKind = graphcontract.PropertyValueKind
type PruneCommittedWithWarningError ¶ added in v0.0.6
type PruneCommittedWithWarningError struct {
Result PruneResult
// contains filtered or unexported fields
}
PruneCommittedWithWarningError reports that a prune operation was committed, but directory sync had a warning.
func (*PruneCommittedWithWarningError) Error ¶ added in v0.0.6
func (e *PruneCommittedWithWarningError) Error() string
Error returns the underlying durability warning.
func (*PruneCommittedWithWarningError) Unwrap ¶ added in v0.0.6
func (e *PruneCommittedWithWarningError) Unwrap() error
Unwrap returns the underlying durability warning.
type PruneRequest ¶ added in v0.0.6
PruneRequest describes the options for a graph pruning operation.
type PruneResult ¶ added in v0.0.6
PruneResult summarizes the entities removed, cascading edges excised, and durable orphans detected.
type PushCommitRecord ¶ added in v1.5.0
type PushCommitRecord struct {
ID string `json:"id"`
Commit graphcontract.Commit `json:"commit"`
}
PushCommitRecord is one commit to register with Rack, matching the "commits" push metadata field Rack's gateway expects.
type PushObject ¶ added in v1.5.0
PushObject is one immutable, content-addressed object carried by a push pack (a materialized graph snapshot referenced by a pushed commit).
type PushPack ¶ added in v1.5.0
type PushPack struct {
// Branch is the branch this pack advances.
Branch string
// BaseCommit is Rack's current wire commit ID for Branch, or "" for an
// initial push publishing the branch's entire history.
BaseCommit string
// TargetCommit is the wire commit ID the push advances Branch to.
TargetCommit string
// Commits are the new commits to register, oldest-ancestor first.
Commits []PushCommitRecord
// Objects are the new content-addressed objects (materialized graph
// snapshots) the pushed commits reference.
Objects []PushObject
// PackFormat identifies the pack frame encoding (always PushPackFormatV2).
PackFormat uint32
// PackHash is the content-addressed hash of PackData.
PackHash string
// PackData is the canonical CBOR-encoded pack frame to upload verbatim.
PackData []byte
// AssetHashes contains the sorted unique list of candidate asset hashes referenced
// by nodes across the pushed commits.
AssetHashes []string
}
PushPack is a fully built, ready-to-send native push payload.
type ReconcileResult ¶ added in v1.5.0
type ReconcileResult struct {
// Commit is the new fast-forward-eligible commit branch was advanced
// to. Its sole parent is remoteBranch's head commit, so a subsequent
// BuildPushPack/push against remoteBranch's real (Rack) head succeeds
// under push's linear-history-only requirement.
Commit ObjectID
// Preview is the merge preview the reconciled commit's content was
// computed from. Callers that need conflict detail on an unclean
// result should inspect Preview.Conflicts (and Preview.Clean is always
// false in that case; ReconcileBranch returns ErrMergeConflicted
// alongside it).
Preview MergePreview
}
ReconcileResult reports the outcome of ReconcileBranch.
type RemoteAuthMode ¶ added in v1.5.0
Remote types and auth modes re-exported from the remote package so CLI commands and callers never need to import internal/remote's config shape directly for persisted state.
type RemoteBranchTracking ¶ added in v1.5.0
type RemoteBranchTracking struct {
// RemoteBranch is the tracked remote branch name.
RemoteBranch string `json:"remoteBranch" toml:"remote_branch"`
// RemoteHeadCommit is the last wire commit ID known for RemoteBranch.
RemoteHeadCommit string `json:"remoteHeadCommit" toml:"remote_head_commit"`
}
RemoteBranchTracking records, for one local branch, which remote branch it tracks and the last wire commit ID known to have been synchronized with Rack for that branch (set after a successful `spl remote branch create` or a push that establishes tracking for a not-yet-tracked branch).
type RemoteConfig ¶ added in v1.5.0
Remote types and auth modes re-exported from the remote package so CLI commands and callers never need to import internal/remote's config shape directly for persisted state.
type Repository ¶
type Repository struct {
// contains filtered or unexported fields
}
Repository provides concurrency-safe access to durable graph, branch, and merge state.
func InitializeClonedRepository ¶ added in v1.6.0
func InitializeClonedRepository(stateDir string, cfg RemoteConfig, branch string, headCommit string, packs [][]byte) (*Repository, int, error)
InitializeClonedRepository creates and initializes a new repository in stateDir from a remote clone payload, installing all commits and graph snapshots carried by packs, setting up remote configuration, and making branch the active branch. If packs is empty (the remote workspace has no commits yet), the repository is seeded with the standard initial skeleton. It returns the opened repository and the count of commits installed from remote.
func InitializeRepository ¶
func InitializeRepository(stateDir string) (*Repository, error)
InitializeRepository creates and durably stores a seeded repository.
func NewSeedRepository ¶
func NewSeedRepository() (*Repository, error)
NewSeedRepository returns an in-memory repository initialized with the seed graph, or an error.
func NewSeedRepositoryWithMergeState ¶
func NewSeedRepositoryWithMergeState(stateDir string) (*Repository, error)
NewSeedRepositoryWithMergeState opens stateDir or initializes a new seeded repository.
func OpenRepository ¶
func OpenRepository(stateDir string) (*Repository, error)
OpenRepository opens an initialized repository without creating state for a new target.
func (*Repository) AbortMergeTransaction ¶
func (r *Repository) AbortMergeTransaction(targetBranch, callerTransactionID string) error
AbortMergeTransaction durably removes an owning transaction and releases its target lease.
func (*Repository) AdvanceBranch ¶
func (r *Repository) AdvanceBranch(branch string) (ObjectID, error)
AdvanceBranch creates and persists a no-content commit on branch unless it is merge leased.
func (*Repository) ApplyCleanBoundMerge ¶
func (r *Repository) ApplyCleanBoundMerge(sourceBranch, targetBranch, transactionID string, binding MergePreviewBinding) (ObjectID, error)
ApplyCleanBoundMerge validates binding and atomically commits a clean merge to targetBranch.
func (*Repository) ApplyConflictedBoundMerge ¶
func (r *Repository) ApplyConflictedBoundMerge(sourceBranch, targetBranch, transactionID string, binding MergePreviewBinding) error
ApplyConflictedBoundMerge persists a target lease and transaction, then returns ErrMergeConflicted.
func (*Repository) ApplyMergePreview ¶
func (r *Repository) ApplyMergePreview(sourceBranch, targetBranch, transactionID string, previewID ObjectID, author, message string) (ObjectID, error)
ApplyMergePreview recomputes and atomically applies the exact clean preview identified by previewID.
func (*Repository) BranchStagingStatus ¶
func (r *Repository) BranchStagingStatus(branch string) (BranchStagingStatus, error)
BranchStagingStatus returns the current shared staging summary for a branch.
func (*Repository) BranchesContaining ¶
func (r *Repository) BranchesContaining(selector ContainmentSelector) (BranchContainmentResult, error)
BranchesContaining returns ordered branches whose history contains the selected entity or snapshot.
func (*Repository) BranchesContainingContext ¶
func (r *Repository) BranchesContainingContext(ctx context.Context, request BranchesContainingRequest) (BranchContainmentResult, error)
BranchesContainingContext returns a context-cancelable bounded branch page. Its limits are required so callers cannot accidentally expose an unbounded public list; legacy callers may continue to use BranchesContaining.
func (*Repository) BuildPushPack ¶ added in v1.5.0
func (r *Repository) BuildPushPack(ctx context.Context, branch, baseCommit string) (PushPack, error)
BuildPushPack builds a native push pack advancing branch from baseCommit (Rack's currently reported wire commit ID for the branch, or "" if Rack has no history for it yet) to the branch's current local head.
BuildPushPack always recomputes wire commit IDs and materialized graph snapshots from scratch across the branch's entire local first-parent history; this repository does not persist any local-to-wire commit ID mapping (that is remote-branch-tracking state, a separate capability). Recomputation is a pure function of each commit's content, so it is always correct, at the cost of walking the full history on every push.
History is traversed as a DAG and topologically sorted (ancestors before descendants), supporting multi-parent merge commits.
func (*Repository) CherryPick ¶ added in v1.2.0
func (r *Repository) CherryPick(request CherryPickRequest) (CherryPickResult, error)
CherryPick computes single-commit graph deltas against its parent, performs 3-way property merging against target HEAD, validates referential integrity and schema rules, and orchestrates atomic commit generation on targetBranch.
func (*Repository) Close ¶
func (r *Repository) Close() error
Close marks the repository unusable and releases its process lock; it is safe to call repeatedly.
func (*Repository) CommitStagedMutationBatch ¶
func (r *Repository) CommitStagedMutationBatch(request CommitStagedMutationRequest) (CommitStagedMutationResult, error)
CommitStagedMutationBatch materializes and commits staged mutations with caller metadata.
func (*Repository) CommitStagedMutations ¶
func (r *Repository) CommitStagedMutations(branch string) (CommitStagedMutationResult, error)
CommitStagedMutations materializes and commits the branch's current staged mutation set.
func (*Repository) CreateBranch ¶
func (r *Repository) CreateBranch(name string, source branch.Source) (branch.CreateResult, error)
CreateBranch atomically creates name at source and persists the new branch when durable.
func (*Repository) DeleteBranch ¶
func (r *Repository) DeleteBranch(name string) (branch.DeleteResult, error)
DeleteBranch atomically deletes a non-default, inactive branch and its staged mutations.
func (*Repository) Diff ¶
func (r *Repository) Diff(request DiffRequest) (DiffResult, error)
Diff returns a deterministic, budgeted page comparing two repository snapshots.
func (*Repository) DiffContext ¶
func (r *Repository) DiffContext(ctx context.Context, request DiffRequest) (DiffResult, error)
DiffContext returns a deterministic, budgeted page and stops scanning when ctx is canceled. MaxResponseBytes applies to DiffResult, not an adapter envelope.
func (*Repository) EnsureBranchHeadProjection ¶
func (r *Repository) EnsureBranchHeadProjection(branch string, commit *ObjectID) (ProjectionStatus, error)
EnsureBranchHeadProjection rebuilds the projection for branch's pinned head. Non-head commits deliberately remain unsupported until historical projections land.
func (*Repository) FilterNodes ¶
func (r *Repository) FilterNodes(request FilterNodesRequest) (FilterNodesResult, error)
FilterNodes returns nodes matching typed metadata predicates through the private projection.
func (*Repository) FilterNodesContext ¶
func (r *Repository) FilterNodesContext(ctx context.Context, request FilterNodesRequest) (FilterNodesResult, error)
FilterNodesContext filters a branch-head projection using only schema-indexed scalar properties and honors cancellation throughout the query.
func (*Repository) FinalizeMergeTransaction ¶
func (r *Repository) FinalizeMergeTransaction(targetBranch, callerTransactionID string) (ObjectID, error)
FinalizeMergeTransaction atomically commits a resolved, restaged transaction and releases its lease.
func (*Repository) Fsck ¶
func (r *Repository) Fsck() (FsckResult, error)
Fsck checks an opened repository's durable state when it has one, or its current immutable in-memory graph otherwise.
func (*Repository) GC ¶
func (r *Repository) GC(options GCOptions) (GCResult, error)
GC packs reachable durable objects and prunes only grace-expired unreachable loose objects. A durable repository's process lock is held for its lifetime; the repository mutex serializes this operation with in-process mutations.
func (*Repository) History ¶
func (r *Repository) History(request HistoryRequest) (HistoryResult, error)
History returns commits that affected the selected entity, or ErrEntityHistoryNotFound.
func (*Repository) HistoryContext ¶
func (r *Repository) HistoryContext(ctx context.Context, request HistoryRequest) (HistoryResult, error)
HistoryContext returns a context-cancelable page of entity history. A zero MaxRows or MaxResponseBytes preserves legacy unbounded History behavior.
func (*Repository) Impact ¶
func (r *Repository) Impact(request ImpactRequest) (ImpactResult, error)
Impact applies Delta in memory and analyzes its outgoing dependency impact. Until the schema models dependency types, weights, criticality, and validators, every edge is an outgoing unit-weight dependency, all nodes have zero criticality, and there are no validators to evaluate.
func (*Repository) ImpactContext ¶
func (r *Repository) ImpactContext(ctx context.Context, request ImpactRequest) (ImpactResult, error)
ImpactContext applies Delta in memory, honors ctx while traversing, and returns a deterministic page. MaxResponseBytes applies only to ImpactResult.
func (*Repository) Initialization ¶
func (r *Repository) Initialization() (Initialization, error)
Initialization returns the current default and active branches, or an error if closed.
func (*Repository) InspectMergeTransaction ¶
func (r *Repository) InspectMergeTransaction(targetBranch, callerTransactionID string) (MergeTransactionStatus, error)
InspectMergeTransaction returns the persisted preview and resolution state to its owner.
func (*Repository) InstallPullPack ¶ added in v1.5.0
func (r *Repository) InstallPullPack(ctx context.Context, branch string, packs [][]byte, expectedHead string) (InstallPullResult, error)
InstallPullPack decodes and installs the given pull packs (as returned by remote.Pull, oldest-to-newest) onto branch's local history, advancing the branch ref only after every commit and object across all packs has been decoded, validated, and materialized successfully.
Each pack must be a canonical CBOR pushPackFrame (the same wire shape BuildPushPack produces), byte-compatible with Rack's sync.PackFrameV2. InstallPullPack requires the first pack's declared base commit to equal branch's current local head's recomputed wire commit ID: pulling a branch with no common ancestor with Rack (a from-scratch bootstrap/clone) is not yet supported (ErrPullBootstrapUnsupported).
InstallPullPack preserves each pulled commit's original Author, Message, and Time exactly as Rack reports them, so a subsequent push recomputes the same wire commit IDs Rack already has.
func (*Repository) InstallReconciliationPack ¶ added in v1.5.0
func (r *Repository) InstallReconciliationPack(ctx context.Context, branch string, packs [][]byte, expectedHead string) (InstallPullResult, error)
InstallReconciliationPack decodes and installs a from-scratch (empty declared base) set of pull packs onto branch, creating branch if it does not yet exist or replacing its head entirely if it does. Unlike InstallPullPack, it does not require branch's current head to already be an ancestor of the installed history: it is intended for a dedicated reconciliation branch that always mirrors Rack's complete current history for the corresponding remote branch, rebuilt fresh on every non-fast-forward reconciliation attempt.
Because every durable object is content-addressed (BLAKE3/CBOR), any commit in the installed history whose content exactly matches a commit already known locally resolves to that same local object ID rather than a new one. In particular, a historical prefix genuinely shared with another local branch (the common ancestor before divergence) collapses onto that branch's existing local commits, giving the graph merge engine a true common ancestor to merge from.
func (*Repository) ListBranches ¶
func (r *Repository) ListBranches() (branch.ListResult, error)
ListBranches returns lexically ordered branch names, or an error if the repository is closed.
func (*Repository) OpenAsset ¶ added in v1.8.0
func (r *Repository) OpenAsset(hash string) (io.ReadCloser, int64, error)
OpenAsset opens the content-addressed asset blob keyed by BLAKE3 hash for streaming.
func (*Repository) PinBranch ¶
func (r *Repository) PinBranch(name string) (ObjectID, error)
PinBranch returns the current immutable commit for a branch. The returned ID remains valid if the branch moves after it has been pinned.
func (*Repository) PinBranchContext ¶
PinBranchContext returns a branch's current immutable commit while honoring cancellation before and after acquiring the repository read lock.
func (*Repository) PinnedEdges ¶
func (r *Repository) PinnedEdges(commitID ObjectID) ([]Edge, error)
PinnedEdges returns canonical edge values from a previously pinned commit.
func (*Repository) PinnedEdgesContext ¶
PinnedEdgesContext returns canonical edge values from a previously pinned commit. It is a snapshot read primitive for graph-specific use cases; callers are responsible for applying their own traversal bounds.
func (*Repository) PinnedNodes ¶ added in v0.0.2
func (r *Repository) PinnedNodes(commitID ObjectID) ([]Node, error)
PinnedNodes returns canonical node values from a previously pinned commit.
func (*Repository) PinnedNodesContext ¶ added in v0.0.2
PinnedNodesContext returns canonical node values from a previously pinned commit. It is a snapshot read primitive for graph-specific use cases.
func (*Repository) PinnedSnapshotRecord ¶
func (r *Repository) PinnedSnapshotRecord(commitID ObjectID) (PinnedSnapshotRecord, error)
PinnedSnapshotRecord returns immutable snapshot roots for a previously pinned commit.
func (*Repository) PinnedSnapshotRecordContext ¶
func (r *Repository) PinnedSnapshotRecordContext(ctx context.Context, commitID ObjectID) (PinnedSnapshotRecord, error)
PinnedSnapshotRecordContext returns immutable snapshot roots while honoring cancellation around the repository lookup.
func (*Repository) PreviewMerge ¶
func (r *Repository) PreviewMerge(sourceBranch, targetBranch string) (MergePreview, error)
PreviewMerge computes a three-way graph merge without changing repository state.
func (*Repository) ProjectionStatus ¶
func (r *Repository) ProjectionStatus() (ProjectionStatus, error)
ProjectionStatus returns the cached projection metadata without exposing physical tables.
func (*Repository) ProjectionStatusContext ¶
func (r *Repository) ProjectionStatusContext(ctx context.Context) (ProjectionStatus, error)
ProjectionStatusContext returns cached projection metadata while honoring cancellation around the repository read.
func (*Repository) Prune ¶ added in v0.0.6
func (r *Repository) Prune(request PruneRequest) (PruneResult, error)
Prune performs two-phase ephemeral entity discovery, cascading edge excision, orphan detection, and commit generation.
func (*Repository) ReadAsset ¶ added in v1.8.0
func (r *Repository) ReadAsset(ctx context.Context, branch, locatorOrNode string) (io.ReadCloser, int64, AssetMetadata, error)
ReadAsset resolves a locator (spool://assets/{hash} or raw hash) or node ID on branch, opening the underlying content-addressable blob stream. If the asset blob is missing locally and a Rack remote is configured, it attempts on-demand retrieval from the remote.
func (*Repository) ReconcileBranch ¶ added in v1.5.0
func (r *Repository) ReconcileBranch(branch, remoteBranch, author, message string) (ReconcileResult, error)
ReconcileBranch rebases branch's independent local changes onto remoteBranch's content, producing a single-parent commit suitable for a fast-forward retry push, and advances branch to it.
It reuses the same deterministic three-way merge computation as `spl merge preview` (source=branch, target=remoteBranch), but — unlike ApplyMergePreview, which records a two-parent merge commit on the target branch — records a clean result as a single-parent commit on branch whose only parent is remoteBranch's head commit. This matters because BuildPushPack (and therefore `spl push`) only supports linear, single-parent history: a real two-parent merge commit could never be pushed. Because the merged content is otherwise identical to a genuine three-way merge, this is a "rebase local changes onto Rack's current truth" operation, not a content-losing shortcut.
If the preview is not clean, branch and remoteBranch are left completely untouched (both histories are retained) and ReconcileBranch returns ErrMergeConflicted alongside the conflicted MergePreview so the caller can report it; the caller may resolve those conflicts with the existing `spl merge preview/apply/conflicts/resolve/finalize` commands against branch and remoteBranch directly, then retry reconciliation.
func (*Repository) RecoverMergeTransactions ¶
func (r *Repository) RecoverMergeTransactions() error
RecoverMergeTransactions restores valid durable merge transactions and discards invalid records.
func (*Repository) Remote ¶ added in v1.5.0
func (r *Repository) Remote() (RemoteConfig, bool, error)
Remote returns the repository's configured Rack remote, or ok=false if none is configured.
func (*Repository) RemoteBranchTracking ¶ added in v1.5.0
func (r *Repository) RemoteBranchTracking(localBranch string) (RemoteBranchTracking, bool, error)
RemoteBranchTracking returns the remote-branch tracking metadata recorded for localBranch, or ok=false if localBranch has no tracked remote branch.
func (*Repository) RemoveRemote ¶ added in v1.5.0
func (r *Repository) RemoveRemote() error
RemoveRemote durably clears any configured Rack remote. It is a no-op if no remote is configured.
func (*Repository) RepositoryID ¶
func (r *Repository) RepositoryID() string
RepositoryID returns the stable identifier for this repository's projection namespace without exposing its storage location or SQLite tables.
func (*Repository) ResolveAssetNode ¶ added in v1.8.0
func (r *Repository) ResolveAssetNode(branch, nodeID string) (string, AssetMetadata, error)
ResolveAssetNode inspects a branch (checking staged mutations first, then the snapshot projection) to resolve an asset node by ID, extracting its canonical BLAKE3 hash and metadata.
func (*Repository) ResolveConflictedMerge ¶
func (r *Repository) ResolveConflictedMerge(request ResolveConflictedMergeRequest) error
ResolveConflictedMerge materializes an owner-selected, schema-valid resolution snapshot.
func (*Repository) ResolveExplicitCommit ¶
func (r *Repository) ResolveExplicitCommit(branch string, requested ObjectID, allowDetached bool) (ObjectID, error)
ResolveExplicitCommit validates an explicit commit selector against a branch.
func (*Repository) ResolveExplicitCommitContext ¶
func (r *Repository) ResolveExplicitCommitContext(ctx context.Context, branch string, requested ObjectID, allowDetached bool) (ObjectID, error)
ResolveExplicitCommitContext validates an explicit commit selector against a branch while honoring cancellation during reachability traversal.
func (*Repository) ResolveMergeTransaction ¶
func (r *Repository) ResolveMergeTransaction(targetBranch, callerTransactionID string, stagedSnapshot ObjectID) error
ResolveMergeTransaction records an existing resolution snapshot for the owning transaction.
func (*Repository) ResolvePinned ¶
func (r *Repository) ResolvePinned(commitID ObjectID, nodeID string) (Resolution, error)
ResolvePinned reads a node from a previously pinned commit.
func (*Repository) ResolvePinnedContext ¶
func (r *Repository) ResolvePinnedContext(ctx context.Context, commitID ObjectID, nodeID string) (Resolution, error)
ResolvePinnedContext reads a node from a previously pinned commit while honoring cancellation during normalization and schema lookup.
func (*Repository) RestageMergeTransaction ¶
func (r *Repository) RestageMergeTransaction(targetBranch, callerTransactionID string) error
RestageMergeTransaction records that the owning transaction's resolution was restaged.
func (*Repository) ScanRetention ¶
func (r *Repository) ScanRetention() (RetentionScan, error)
ScanRetention collects durable retention roots and verifies their complete object graph. It fails closed: callers must not delete objects on an error.
func (*Repository) SearchNodes ¶
func (r *Repository) SearchNodes(request SearchNodesRequest) (SearchNodesResult, error)
SearchNodes searches node titles, string properties, labels, and tags through the private FTS5 projection.
func (*Repository) SearchNodesContext ¶
func (r *Repository) SearchNodesContext(ctx context.Context, request SearchNodesRequest) (SearchNodesResult, error)
SearchNodesContext searches the branch-head projection with a parameterized FTS5 match expression and honors cancellation while querying and materializing the page.
func (*Repository) SetRemote ¶ added in v1.5.0
func (r *Repository) SetRemote(cfg RemoteConfig) error
SetRemote validates and durably persists cfg as the repository's Rack remote configuration. cfg must never contain credentials: SetRemote rejects endpoint or repo_id values that look like pasted-in secrets.
func (*Repository) SetRemoteBranchTracking ¶ added in v1.5.0
func (r *Repository) SetRemoteBranchTracking(localBranch, remoteBranch, remoteHeadCommit string) error
SetRemoteBranchTracking durably records that localBranch tracks remoteBranch at remoteHeadCommit, overwriting any prior tracking entry for localBranch.
func (*Repository) StageAsset ¶ added in v1.8.0
func (r *Repository) StageAsset(ctx context.Context, req AssetAddRequest) (AssetAddResult, error)
StageAsset ingests an external reference document into the loose content-addressable storage and stages a corresponding Asset node into the branch mutation set.
func (*Repository) StageMutationBatch ¶
func (r *Repository) StageMutationBatch(request StageMutationRequest) (StageMutationResult, error)
StageMutationBatch atomically replaces a branch's staged mutation set after validating every operation against the branch head and this batch's additions.
func (*Repository) StageSchemaMigration ¶
func (r *Repository) StageSchemaMigration(request SchemaMigrationRequest) (StageMutationResult, error)
StageSchemaMigration atomically replaces a branch's staged set with a parsed canonical target schema and the complete graph mutations needed to conform to it.
func (*Repository) StageSchemaMigrationBatch ¶
func (r *Repository) StageSchemaMigrationBatch(request SchemaMigrationRequest) (StageMutationResult, error)
StageSchemaMigrationBatch is an alias for StageSchemaMigration.
func (*Repository) StateDir ¶ added in v1.6.0
func (r *Repository) StateDir() string
StateDir returns the durable repository state directory path, or "" for in-memory repositories.
func (*Repository) SwitchBranch ¶
func (r *Repository) SwitchBranch(name string) (branch.SwitchResult, error)
SwitchBranch atomically makes an existing branch active and persists that selection.
func (*Repository) ValidatePinnedSchema ¶
func (r *Repository) ValidatePinnedSchema(commitID ObjectID) (SchemaValidationResolution, error)
ValidatePinnedSchema validates the complete immutable graph at a previously pinned commit against that snapshot's schema.
type Resolution ¶
type Resolution struct {
// Node is the immutable node value read from the pinned commit.
Node Node
// Commit identifies the commit from which Node was resolved.
Commit ObjectID
// Snapshot identifies the graph snapshot containing Node.
Snapshot ObjectID
// NodeRoot identifies the durable root of the snapshot's node projection.
NodeRoot ObjectID
// SchemaVersion identifies the schema stored by the snapshot.
SchemaVersion uint16
}
Resolution is an immutable view of a node resolved from a pinned commit.
type ResolveConflictedMergeRequest ¶
type ResolveConflictedMergeRequest struct {
TargetBranch string `json:"targetBranch"`
TransactionID string `json:"transactionId"`
PreviewID ObjectID `json:"previewId"`
Selections []MergeResolutionSelection `json:"selections"`
Overrides []MutationOperation `json:"overrides,omitempty"`
}
ResolveConflictedMergeRequest supplies every conflict selection and optional corrective mutations.
type RetentionScan ¶
type RetentionScan struct {
Roots []ObjectID
Objects map[ObjectID]struct{}
RootCount uint64
ReachableObjects uint64
}
RetentionScan is the verified object set that a future maintenance operation may retain. Objects contains every object reachable from Roots.
type SchemaMigrationRequest ¶
type SchemaMigrationRequest struct {
// Branch identifies the branch to migrate.
Branch string `json:"branch"`
// SchemaTOML contains the complete target schema definition.
SchemaTOML []byte `json:"schemaToml"`
// Operations transforms the base graph into one conforming to the target schema.
// It may be empty when the base graph already conforms.
Operations []MutationOperation `json:"operations"`
}
SchemaMigrationRequest atomically stages a schema replacement and its complete graph mutation batch against Branch.
type SchemaSnapshot ¶
type SchemaSnapshot = graphcontract.SchemaSnapshot
func BuiltinSchemaSnapshot ¶
func BuiltinSchemaSnapshot() SchemaSnapshot
func DecodeSchemaTOML ¶
func DecodeSchemaTOML(data []byte) (SchemaSnapshot, error)
DecodeSchemaTOML delegates schema parsing and canonical normalization to the public graph contract.
func DecodeSchemaTOMLReader ¶
func DecodeSchemaTOMLReader(reader io.Reader) (SchemaSnapshot, error)
DecodeSchemaTOMLReader decodes a schema definition from a TOML stream.
func ParseSchemaTOML ¶
func ParseSchemaTOML(data []byte) (SchemaSnapshot, error)
ParseSchemaTOML is an alias for DecodeSchemaTOML.
type SchemaValidationError ¶
type SchemaValidationError = graphcontract.SchemaValidationError
type SchemaValidationResolution ¶
type SchemaValidationResolution struct {
// Commit identifies the commit that was validated.
Commit ObjectID
// Snapshot identifies the validated graph snapshot.
Snapshot ObjectID
// SchemaRoot identifies the schema used for validation.
SchemaRoot ObjectID
// Schema is the normalized schema used for validation.
Schema SchemaSnapshot
// Valid reports whether the graph conforms to Schema.
Valid bool
// Violations contains each failed constraint when Valid is false.
Violations []SchemaViolation
}
SchemaValidationResolution is an immutable schema-validation result for a pinned commit.
type SchemaViolation ¶
type SchemaViolation = graphcontract.SchemaViolation
type SchemaViolationCode ¶
type SchemaViolationCode = graphcontract.SchemaViolationCode
type SearchNodeMatch ¶
type SearchNodeMatch struct {
Node Node `json:"node"`
Score float64 `json:"score"`
MatchedFields []string `json:"matchedFields"`
Snippets map[string]string `json:"snippets"`
}
SearchNodeMatch is a projection-backed lexical match. MatchedFields uses the FTS field names title, body, labels, and tags; Snippets contains marked excerpts for each matched field.
type SearchNodesRequest ¶
type SearchNodesRequest struct {
Branch string `json:"branch"`
Commit ObjectID `json:"commit"`
Query string `json:"query"`
MaxRows int `json:"maxRows"`
MaxResponseBytes int `json:"maxResponseBytes"`
ContinuationToken string `json:"continuationToken,omitempty"`
}
SearchNodesRequest describes a bounded lexical search of the branch-head projection. Commit must be a commit previously pinned from Branch and must still be Branch's head when the query runs.
type SearchNodesResult ¶
type SearchNodesResult struct {
Branch string `json:"branch"`
Commit ObjectID `json:"commit"`
Snapshot ObjectID `json:"snapshot"`
Matches []SearchNodeMatch `json:"matches"`
ContinuationToken string `json:"continuationToken,omitempty"`
}
SearchNodesResult is one deterministic page of lexical matches.
type StageMutationRequest ¶
type StageMutationRequest struct {
// Branch identifies the branch to stage against.
Branch string `json:"branch"`
// Operations is the complete, validated replacement mutation set.
Operations []MutationOperation `json:"operations"`
}
StageMutationRequest replaces the staged mutations for Branch.
type StageMutationResult ¶
type StageMutationResult struct {
// Branch identifies the branch whose mutations were staged.
Branch string `json:"branch"`
// BaseCommit is the branch head used for validation.
BaseCommit ObjectID `json:"baseCommit"`
// Operations is the number of staged operations.
Operations int `json:"operations"`
}
StageMutationResult summarizes the persisted shared staged mutation set.
type StagedMutationSet ¶
type StagedMutationSet struct {
// Branch identifies the branch that owns the shared staged set.
Branch string `json:"branch"`
// BaseCommit is the branch head validated when the set was staged.
BaseCommit ObjectID `json:"baseCommit"`
// Operations is the complete replacement set to materialize on commit.
Operations []MutationOperation `json:"operations"`
// TargetSchema is an optional canonical schema installed with Operations.
// A nil value preserves the base snapshot schema.
TargetSchema *SchemaSnapshot `json:"targetSchema,omitempty"`
}
StagedMutationSet is the shared, durable staged change set for one branch.
type UnsupportedPackVersionError ¶
type UnsupportedPackVersionError = graphcontract.UnsupportedPackVersionError
UnsupportedPackVersionError identifies a pack, index, or manifest format this repository cannot safely read.
type WorkspaceID ¶ added in v0.0.7
func NewWorkspaceID ¶ added in v0.0.7
func NewWorkspaceID() (WorkspaceID, error)
type WorkspaceManifest ¶ added in v0.0.8
WorkspaceManifest declares a checkout's portable workspace binding.
func DiscoverWorkspaceManifest ¶ added in v0.0.8
func DiscoverWorkspaceManifest(workingDirectory string) (string, WorkspaceManifest, bool, error)
DiscoverWorkspaceManifest searches a directory and its ancestors for a manifest.
type WorkspaceMigrationRequiredError ¶ added in v1.6.0
WorkspaceMigrationRequiredError indicates that a repository cannot be opened because its format_version is older than the current Spool version, and tells the user to run the explicit migration command targeting the versions.
func (*WorkspaceMigrationRequiredError) Error ¶ added in v1.6.0
func (e *WorkspaceMigrationRequiredError) Error() string
type WorkspaceName ¶ added in v0.0.7
func ParseWorkspaceName ¶ added in v0.0.7
func ParseWorkspaceName(value string) (WorkspaceName, error)
type WorkspaceRegistry ¶ added in v0.0.7
func LoadWorkspaceRegistry ¶ added in v0.0.7
func LoadWorkspaceRegistry(root string) (WorkspaceRegistry, error)
Source Files
¶
- asset.go
- cherrypick.go
- clone.go
- diff.go
- durable_replace_nonwindows.go
- fsck.go
- gc.go
- history.go
- impact.go
- merge_preview.go
- merge_store.go
- migration.go
- model.go
- object_store.go
- pack_contract.go
- pack_storage.go
- performance.go
- pinned_edges.go
- pinned_nodes.go
- projection.go
- projection_cache.go
- prolly_tree.go
- prune.go
- pull_pack.go
- push_pack.go
- query_page.go
- reachability.go
- reconcile_merge.go
- reflog_retention.go
- remote.go
- repository.go
- repository_state.go
- retrieval.go
- schema.go
- schema_validator.go
- working_state.go
- workspace.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package asset provides content-addressable storage, URI resolution, and MIME detection for contextual reference assets in Spool repositories.
|
Package asset provides content-addressable storage, URI resolution, and MIME detection for contextual reference assets in Spool repositories. |
|
Package branch defines local branch lifecycle operations.
|
Package branch defines local branch lifecycle operations. |
|
Package cherrypick defines operations for selectively transplanting commits onto target branches.
|
Package cherrypick defines operations for selectively transplanting commits onto target branches. |
|
Package fsck exposes the durable repository integrity-check use case and service.
|
Package fsck exposes the durable repository integrity-check use case and service. |
|
Package initialization exposes the repository initialization use case.
|
Package initialization exposes the repository initialization use case. |
|
Package merge defines merge transaction lifecycle operations.
|
Package merge defines merge transaction lifecycle operations. |
|
Package prune defines graph pruning operations for excising ephemeral planning entities.
|
Package prune defines graph pruning operations for excising ephemeral planning entities. |