repository

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package repository provides durable graph storage and repository lifecycle operations.

Package repository provides durable graph storage and repository lifecycle operations.

Index

Constants

View Source 
const (
	// MaxSchemaLabelLength bounds schema labels and edge types in bytes.
	MaxSchemaLabelLength = 128
	// MaxSchemaPropertyKeyLength bounds schema and graph property keys in bytes.
	MaxSchemaPropertyKeyLength = 128
	// MaxPropertyStringLength bounds a string property value in bytes.
	MaxPropertyStringLength = 16 * 1024
	// MaxPropertyEntries bounds the aggregate number of values and map entries in one property set.
	MaxPropertyEntries = 256
	// MaxPropertyAggregateBytes bounds strings and keys in one property set.
	MaxPropertyAggregateBytes = 64 * 1024
	// MaxPropertyDepth bounds nesting in list and map property values.
	MaxPropertyDepth = 16
)
View Source 
const (
	// PackMagic identifies an IDG pack stream.
	PackMagic = "IDGP"
	// PackFormatVersion is the version encoded in every pack header.
	PackFormatVersion uint32 = 2
	// PackIndexFormatVersion is the version of the sidecar object index.
	PackIndexFormatVersion uint32 = 1
	// PackManifestFormatVersion is the version of objects/info/packs.
	PackManifestFormatVersion uint32 = 1
)
View Source 
const BuiltinSchemaVersion uint16 = 1

BuiltinSchemaVersion is the version of the initial permissive schema.

View Source 
const DefaultGCGracePeriod = defaultGCGracePeriod

DefaultGCGracePeriod is the retention period applied when GCOptions.GracePeriod is zero.

View Source 
const SeedNodeID = "11111111-1111-4111-8111-111111111111"

SeedNodeID is the stable identifier of the node in every seeded repository.

View Source 
const UniversalModifierLabel = "Ephemeral"

UniversalModifierLabel identifies the intrinsic cross-cutting modifier label.

Variables

View Source 
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")
)
View Source 
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")
)
View Source 
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")
)
View Source 
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")
)
View Source 
var (
	// ErrInvalidPropertyValue reports a property value with an unknown kind or a
	// non-finite floating-point value.
	ErrInvalidPropertyValue = errors.New("invalid property value")
	// ErrInvalidSchemaSnapshot reports a schema snapshot without a version.
	ErrInvalidSchemaSnapshot = errors.New("invalid schema snapshot")
	// ErrInvalidSchemaDefinition reports inconsistent or unsupported schema rules.
	ErrInvalidSchemaDefinition = errors.New("invalid schema definition")
	// ErrInvalidSchemaIdentifier reports a label, type, or property key unsafe for storage.
	ErrInvalidSchemaIdentifier = errors.New("invalid schema identifier")
	// ErrPropertyValueLimit reports a property value exceeding an ingestion limit.
	ErrPropertyValueLimit = errors.New("property value exceeds limit")
)
View Source 
var (
	// ErrPackCorrupt reports malformed or inconsistent pack, index, or manifest data.
	ErrPackCorrupt = errors.New("pack storage is corrupt")
	// ErrUnsupportedPackVersion reports a pack storage format newer or older than this repository supports.
	ErrUnsupportedPackVersion = errors.New("unsupported pack storage version")
	// ErrGCCorrupt reports corruption that prevents GC from safely deciding what to retain.
	ErrGCCorrupt = errors.New("GC cannot continue with corrupt repository data")
)
View Source 
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 reports a projection that could not be made ready.
	ErrProjectionUnavailable = errors.New("projection is unavailable")
)
View Source 
var (
	ErrProtectedBranch          = prune.ErrProtectedBranch
	ErrUncommittedStagedChanges = prune.ErrUncommittedStagedChanges
)

Pruning errors re-exported from the prune package.

View Source 
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")
)
View Source 
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")
)
View Source 
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")
)
View Source 
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")
)
View Source 
var (
	ErrWorkspaceNotFound                = workspace.ErrWorkspaceNotFound
	ErrWorkspaceNotRegistered           = workspace.ErrWorkspaceNotRegistered
	ErrWorkspacePathAlreadyAttached     = workspace.ErrPathAlreadyAttached
	ErrWorkspaceInvalidName             = workspace.ErrInvalidName
	ErrWorkspaceInvalidID               = workspace.ErrInvalidID
	ErrWorkspaceInvalid                 = workspace.ErrInvalidWorkspace
	ErrWorkspaceInvalidRegistry         = workspace.ErrInvalidRegistry
	ErrWorkspaceInvalidStorageRoot      = workspace.ErrInvalidStorageRoot
	ErrWorkspaceStorageRootUnavailable  = workspace.ErrStorageRootUnavailable
	ErrWorkspaceInvalidCurrentWorkspace = workspace.ErrInvalidCurrentWorkspace
)

Workspace sentinel errors re-exported from the workspace package.

View Source 
var ErrFsckCorrupt = errors.New("repository integrity check failed")

ErrFsckCorrupt reports that Fsck found one or more integrity violations.

View Source 
var (
	// ErrInvalidSchemaTOML reports malformed TOML or TOML that does not match
	// the schema authoring format.
	ErrInvalidSchemaTOML = errors.New("invalid schema TOML")
)
View Source 
var (
	// ErrSchemaValidation reports graph contents that do not satisfy a schema.
	ErrSchemaValidation = errors.New("schema validation failed")
)

Functions

func AttachWorkspacePath added in v0.0.7 

func AttachWorkspacePath(root string, name WorkspaceName, path string) error

AttachWorkspacePath associates path with workspace name.

func CanonicalStoredWorkspacePath added in v0.0.7 

func CanonicalStoredWorkspacePath(path string) (string, error)

CanonicalStoredWorkspacePath resolves target path for registry persistence.

func CanonicalWorkspacePath added in v0.0.7 

func CanonicalWorkspacePath(path string) (string, error)

CanonicalWorkspacePath resolves target path to an absolute path.

func ClearCurrentWorkspace added in v0.0.7 

func ClearCurrentWorkspace(root string) error

ClearCurrentWorkspace removes the active workspace preference file.

func RepositoryWorkspacePath added in v0.0.7 

func RepositoryWorkspacePath(root string, id WorkspaceID) (string, error)

RepositoryWorkspacePath constructs the state directory path for a workspace.

func SetCurrentWorkspace added in v0.0.7 

func SetCurrentWorkspace(root string, name WorkspaceName) error

SetCurrentWorkspace persists the active workspace preference.

func UpdateWorkspaceRegistry added in v0.0.7 

func UpdateWorkspaceRegistry(root string, update func(*WorkspaceRegistry) error) error

UpdateWorkspaceRegistry executes a mutation closure under the workspace lock.

func ValidateSchemaSnapshot 

func ValidateSchemaSnapshot(schema SchemaSnapshot, nodes map[string]Node, edges map[string]Edge) error

ValidateSchemaSnapshot checks fully materialized graph entities against schema. It never mutates nodes or edges. Invalid schemas are returned as their normalization errors; graph violations are returned as a *SchemaValidationError.

func WorkspaceRegistryPath added in v0.0.7 

func WorkspaceRegistryPath(root string) (string, error)

WorkspaceRegistryPath returns the registry file path within root.

func WorkspaceStorageRoot added in v0.0.7 

func WorkspaceStorageRoot() (string, error)

WorkspaceStorageRoot returns the platform-specific data directory.

Types

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 

type BranchSource = branch.Source

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 struct {
	SourceMin uint32 `json:"sourceMin,omitempty" cbor:"1,keyasint,omitempty"`
	SourceMax uint32 `json:"sourceMax,omitempty" cbor:"2,keyasint,omitempty"`
	TargetMin uint32 `json:"targetMin,omitempty" cbor:"3,keyasint,omitempty"`
	TargetMax uint32 `json:"targetMax,omitempty" cbor:"4,keyasint,omitempty"`
}

Cardinality bounds incoming and outgoing edges of an edge type. A maximum of zero is unbounded.

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 struct {
	// ID uniquely identifies the edge within a graph snapshot.
	ID string `json:"id" cbor:"1,keyasint"`
	// Source identifies the edge's originating node.
	Source string `json:"source" cbor:"2,keyasint"`
	// Target identifies the edge's destination node.
	Target string `json:"target" cbor:"3,keyasint"`
	// Type identifies the edge's relationship type.
	Type string `json:"type,omitempty" cbor:"4,keyasint,omitempty"`
	// Properties holds typed, recursively composable edge properties.
	Properties map[string]PropertyValue `json:"properties" cbor:"5,keyasint"`
}

Edge is the immutable edge representation stored in a graph snapshot.

func (Edge) Equal 

func (e Edge) Equal(other Edge) bool

Equal reports semantic equality after canonical normalization.

func (Edge) MarshalCBOR 

func (e Edge) MarshalCBOR() ([]byte, error)

MarshalCBOR ensures omitted and explicitly empty properties have one canonical encoding without changing their in-memory representation.

func (Edge) Normalize 

func (e Edge) Normalize() (Edge, error)

Normalize returns a canonical edge with normalized property values.

type EdgeTypeRule 

type EdgeTypeRule struct {
	Type         string         `json:"type" cbor:"1,keyasint"`
	Properties   []PropertyRule `json:"properties,omitempty" cbor:"2,keyasint,omitempty"`
	SourceLabels []string       `json:"sourceLabels,omitempty" cbor:"3,keyasint,omitempty"`
	TargetLabels []string       `json:"targetLabels,omitempty" cbor:"4,keyasint,omitempty"`
	Cardinality  Cardinality    `json:"cardinality" cbor:"5,keyasint"`
}

EdgeTypeRule defines constraints for edges of Type.

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.

func (*FsckError) Error 

func (e *FsckError) Error() string

func (*FsckError) Unwrap 

func (e *FsckError) Unwrap() error

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 

type GCCommittedWithWarningError struct {
	Result GCResult
	Err    error
}

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 string

GlobalInvariant names a repository-wide invariant enforced by a schema validator. 

const (
	// GlobalInvariantAcyclic requires the directed graph to contain no cycles.
	GlobalInvariantAcyclic GlobalInvariant = "acyclic"
	// GlobalInvariantNoSelfLoop disallows edges whose endpoints are identical.
	GlobalInvariantNoSelfLoop GlobalInvariant = "no-self-loop"
)

type GraphSnapshot 

type GraphSnapshot struct {
	NodeRoot   ObjectID `cbor:"1,keyasint"`
	EdgeRoot   ObjectID `cbor:"2,keyasint"`
	OutAdjRoot ObjectID `cbor:"3,keyasint"`
	InAdjRoot  ObjectID `cbor:"4,keyasint"`
	SchemaRoot ObjectID `cbor:"5,keyasint"`
	NodeCount  uint64   `cbor:"6,keyasint"`
	EdgeCount  uint64   `cbor:"7,keyasint"`
}

GraphSnapshot is 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 MergeChange 

type MergeChange struct {
	Entity string `json:"entity"`
	ID     string `json:"id"`
	Change string `json:"change"`
}

MergeChange describes an entity changed from the target snapshot by a preview.

type MergeConflict 

type MergeConflict struct {
	// ConflictID is the deterministic identifier used when selecting a resolution.
	ConflictID string `json:"conflictId"`
	// Category is "structural", "schema", or "semantic".
	Category string `json:"category"`
	// Entity is "node", "edge", or "schema".
	Entity string `json:"entity"`
	// ID identifies the affected graph entity when applicable.
	ID string `json:"id,omitempty"`
	// Field identifies the overlapping field or property key.
	Field string `json:"field,omitempty"`
	// Paths identifies the affected graph locations in deterministic order.
	Paths []string `json:"paths"`
}

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 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 struct {
	// ID uniquely identifies the node within a graph snapshot.
	ID string `json:"id" cbor:"1,keyasint"`
	// Title is the node's display value and compatibility field.
	Title string `json:"title" cbor:"2,keyasint"`
	// Labels identifies the node's sorted, unique type labels.
	Labels []string `json:"labels" cbor:"3,keyasint"`
	// Properties holds typed, recursively composable node properties.
	Properties map[string]PropertyValue `json:"properties" cbor:"4,keyasint"`
}

Node is the immutable node representation stored in a graph snapshot.

func (Node) Equal 

func (n Node) Equal(other Node) bool

Equal reports semantic equality after canonical normalization.

func (Node) MarshalCBOR 

func (n Node) MarshalCBOR() ([]byte, error)

MarshalCBOR ensures omitted and explicitly empty collections have one canonical encoding without changing their in-memory representation.

func (Node) Normalize 

func (n Node) Normalize() (Node, error)

Normalize returns a canonical node with sorted, deduplicated labels and normalized property values.

type NodeLabelRule 

type NodeLabelRule struct {
	Label            string         `json:"label" cbor:"1,keyasint"`
	Properties       []PropertyRule `json:"properties,omitempty" cbor:"2,keyasint,omitempty"`
	NaturalKey       []string       `json:"naturalKey,omitempty" cbor:"3,keyasint,omitempty"`
	NaturalKeyUnique bool           `json:"naturalKeyUnique,omitempty" cbor:"4,keyasint,omitempty"`
}

NodeLabelRule defines constraints for nodes carrying Label.

type ObjectID 

type ObjectID string

ObjectID is the content-derived identifier of a durable repository object.

type PackCompression 

type PackCompression string

PackCompression identifies the compression applied to a packed object envelope. 

const (
	// PackCompressionZstd is the required compression for PackFormatVersion.
	PackCompressionZstd PackCompression = "zstd"
)

type PackCorruptionError 

type PackCorruptionError struct {
	Pack   PackID
	Object ObjectID
	Offset uint64
	Detail string
}

PackCorruptionError identifies a failed pack, index, or manifest validation. Object and Offset are omitted when corruption is not associated with an entry.

func (*PackCorruptionError) Error 

func (e *PackCorruptionError) Error() string

Error implements error.

func (*PackCorruptionError) Unwrap 

func (e *PackCorruptionError) Unwrap() error

Unwrap makes PackCorruptionError match ErrPackCorrupt.

type PackID 

type PackID string

PackID identifies one immutable pack and its paired index.

type PackIndexEntry 

type PackIndexEntry struct {
	Object           ObjectID `json:"object"`
	Offset           uint64   `json:"offset"`
	CompressedSize   uint64   `json:"compressedSize"`
	UncompressedSize uint64   `json:"uncompressedSize"`
	CRC32            uint32   `json:"crc32"`
}

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 struct {
	Version uint32         `json:"version"`
	Packs   []PackMetadata `json:"packs"`
}

PackManifest is the atomically replaced list of active packs.

type PackMetadata 

type PackMetadata struct {
	ID          PackID          `json:"id"`
	Version     uint32          `json:"version"`
	Compression PackCompression `json:"compression"`
	ObjectCount uint32          `json:"objectCount"`
}

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 string

PropertyKind identifies the concrete value carried by a PropertyValue. 

const (
	PropertyNull    PropertyKind = "null"
	PropertyBool    PropertyKind = "bool"
	PropertyInteger PropertyKind = "integer"
	PropertyFloat   PropertyKind = "float"
	PropertyString  PropertyKind = "string"
	PropertyList    PropertyKind = "list"
	PropertyMap     PropertyKind = "map"
)

type PropertyRule 

type PropertyRule struct {
	Key      string         `json:"key" cbor:"1,keyasint"`
	Required bool           `json:"required" cbor:"2,keyasint"`
	Types    []PropertyKind `json:"types" cbor:"3,keyasint"`
	Indexed  bool           `json:"indexed,omitempty" cbor:"4,keyasint,omitempty"`
}

PropertyRule defines whether a property is required, indexed, and its allowed value kinds.

type PropertyValue 

type PropertyValue struct {
	Kind    PropertyKind             `json:"kind" cbor:"1,keyasint"`
	Bool    bool                     `json:"bool,omitempty" cbor:"2,keyasint,omitempty"`
	Integer int64                    `json:"integer,omitempty" cbor:"3,keyasint,omitempty"`
	Float   float64                  `json:"float,omitempty" cbor:"4,keyasint,omitempty"`
	String  string                   `json:"string,omitempty" cbor:"5,keyasint,omitempty"`
	List    []PropertyValue          `json:"list,omitempty" cbor:"6,keyasint,omitempty"`
	Map     map[string]PropertyValue `json:"map,omitempty" cbor:"7,keyasint,omitempty"`
}

PropertyValue is a tagged, recursively composable graph property value. Only the field associated with Kind is significant.

func BoolPropertyValue 

func BoolPropertyValue(value bool) PropertyValue

BoolPropertyValue returns a boolean property value.

func FloatPropertyValue 

func FloatPropertyValue(value float64) PropertyValue

FloatPropertyValue returns a floating-point property value.

func IntegerPropertyValue 

func IntegerPropertyValue(value int64) PropertyValue

IntegerPropertyValue returns an integer property value.

func ListPropertyValue 

func ListPropertyValue(value []PropertyValue) PropertyValue

ListPropertyValue returns a list property value.

func MapPropertyValue 

func MapPropertyValue(value map[string]PropertyValue) PropertyValue

MapPropertyValue returns a string-keyed map property value.

func NullPropertyValue 

func NullPropertyValue() PropertyValue

NullPropertyValue returns the canonical null property value.

func StringPropertyValue 

func StringPropertyValue(value string) PropertyValue

StringPropertyValue returns a string property value.

func (PropertyValue) Equal 

func (v PropertyValue) Equal(other PropertyValue) bool

Equal reports semantic equality after canonical normalization.

func (PropertyValue) Normalize 

func (v PropertyValue) Normalize() (PropertyValue, error)

Normalize returns the canonical representation of v. It clears fields that do not belong to v.Kind, recursively normalizes values, and normalizes negative zero to zero. CBOR canonical encoding deterministically orders the resulting string-keyed maps.

type PropertyValueKind 

type PropertyValueKind = PropertyKind

PropertyValueKind is an alias retained for callers that prefer the explicit type name.

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 

type PruneRequest = prune.Request

PruneRequest describes the options for a graph pruning operation.

type PruneResult added in v0.0.6 

type PruneResult = prune.Result

PruneResult summarizes the entities removed, cascading edges excised, and durable orphans detected.

type Repository 

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

Repository provides concurrency-safe access to durable graph, branch, and merge state.

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) 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) ListBranches 

func (r *Repository) ListBranches() (branch.ListResult, error)

ListBranches returns lexically ordered branch names, or an error if the repository is closed.

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 

func (r *Repository) PinBranchContext(ctx context.Context, name string) (ObjectID, error)

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 

func (r *Repository) PinnedEdgesContext(ctx context.Context, commitID ObjectID) ([]Edge, error)

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 

func (r *Repository) PinnedNodesContext(ctx context.Context, commitID ObjectID) ([]Node, error)

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) RecoverMergeTransactions 

func (r *Repository) RecoverMergeTransactions() error

RecoverMergeTransactions restores valid durable merge transactions and discards invalid records.

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) 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) 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) 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 struct {
	Version          uint16            `json:"version" cbor:"0,keyasint"`
	Permissive       bool              `json:"permissive" cbor:"1,keyasint"`
	NodeRules        []NodeLabelRule   `json:"nodeRules,omitempty" cbor:"2,keyasint,omitempty"`
	EdgeRules        []EdgeTypeRule    `json:"edgeRules,omitempty" cbor:"3,keyasint,omitempty"`
	GlobalInvariants []GlobalInvariant `json:"globalInvariants,omitempty" cbor:"4,keyasint,omitempty"`
}

SchemaSnapshot is the canonical schema object referenced by a graph snapshot. Version one is retained as the permissive built-in schema; later versions may declare node, edge, and repository-wide validation rules.

func BuiltinSchemaSnapshot 

func BuiltinSchemaSnapshot() SchemaSnapshot

BuiltinSchemaSnapshot returns the built-in versioned permissive schema.

func DecodeSchemaTOML 

func DecodeSchemaTOML(data []byte) (SchemaSnapshot, error)

DecodeSchemaTOML decodes a schema definition from TOML and returns its normalized canonical representation. Unknown keys are rejected so a typo cannot silently weaken validation.

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.

func (SchemaSnapshot) Normalize 

func (s SchemaSnapshot) Normalize() (SchemaSnapshot, error)

Normalize validates and canonicalizes a schema snapshot.

type SchemaValidationError 

type SchemaValidationError struct {
	Violations []SchemaViolation
}

SchemaValidationError contains every violation found while validating a materialized graph. Violations are sorted lexically for stable previews.

func (*SchemaValidationError) Error 

func (e *SchemaValidationError) Error() string

Error implements error.

func (*SchemaValidationError) Unwrap 

func (e *SchemaValidationError) Unwrap() error

Unwrap makes SchemaValidationError match ErrSchemaValidation.

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 struct {
	Code     SchemaViolationCode `json:"code"`
	Entity   string              `json:"entity"`
	EntityID string              `json:"entityID"`
	Rule     string              `json:"rule,omitempty"`
	Field    string              `json:"field,omitempty"`
	Expected string              `json:"expected,omitempty"`
	Actual   string              `json:"actual,omitempty"`
}

SchemaViolation is one stable, machine-readable failed graph constraint. Entity and EntityID identify the affected graph value. Rule identifies the schema label, edge type, or global invariant, while Field narrows that rule to a property or endpoint when applicable.

type SchemaViolationCode 

type SchemaViolationCode string

SchemaViolationCode identifies the kind of failed schema constraint. 

const (
	SchemaViolationInvalidNode          SchemaViolationCode = "invalid-node"
	SchemaViolationInvalidEdge          SchemaViolationCode = "invalid-edge"
	SchemaViolationNodeID               SchemaViolationCode = "node-id"
	SchemaViolationEdgeID               SchemaViolationCode = "edge-id"
	SchemaViolationNodeLabel            SchemaViolationCode = "node-label"
	SchemaViolationEdgeType             SchemaViolationCode = "edge-type"
	SchemaViolationRequiredProperty     SchemaViolationCode = "required-property"
	SchemaViolationPropertyType         SchemaViolationCode = "property-type"
	SchemaViolationMissingSource        SchemaViolationCode = "missing-source"
	SchemaViolationMissingTarget        SchemaViolationCode = "missing-target"
	SchemaViolationSourceLabel          SchemaViolationCode = "source-label"
	SchemaViolationTargetLabel          SchemaViolationCode = "target-label"
	SchemaViolationSourceCardinalityMin SchemaViolationCode = "source-cardinality-min"
	SchemaViolationSourceCardinalityMax SchemaViolationCode = "source-cardinality-max"
	SchemaViolationTargetCardinalityMin SchemaViolationCode = "target-cardinality-min"
	SchemaViolationTargetCardinalityMax SchemaViolationCode = "target-cardinality-max"
	SchemaViolationNaturalKeyUnique     SchemaViolationCode = "natural-key-unique"
	SchemaViolationAcyclic              SchemaViolationCode = "acyclic"
	SchemaViolationNoSelfLoop           SchemaViolationCode = "no-self-loop"
)

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 struct {
	Format  string
	Version uint32
}

UnsupportedPackVersionError identifies a pack, index, or manifest format this repository cannot safely read.

func (*UnsupportedPackVersionError) Error 

func (e *UnsupportedPackVersionError) Error() string

Error implements error.

func (*UnsupportedPackVersionError) Unwrap 

func (e *UnsupportedPackVersionError) Unwrap() error

Unwrap makes UnsupportedPackVersionError match ErrUnsupportedPackVersion.

type Workspace added in v0.0.7 

type Workspace = workspace.Workspace

Workspace domain types re-exported from the workspace package.

type WorkspaceID added in v0.0.7 

type WorkspaceID = workspace.ID

Workspace domain types re-exported from the workspace package.

func NewWorkspaceID added in v0.0.7 

func NewWorkspaceID() (WorkspaceID, error)

NewWorkspaceID generates a new random hexadecimal workspace identity.

type WorkspaceMatch added in v0.0.7 

type WorkspaceMatch = workspace.WorkspaceMatch

Workspace domain types re-exported from the workspace package.

func FindWorkspace added in v0.0.7 

func FindWorkspace(root, targetDirectory string) (WorkspaceMatch, error)

FindWorkspace selects the workspace whose attached paths match targetDirectory.

type WorkspaceName added in v0.0.7 

type WorkspaceName = workspace.Name

Workspace domain types re-exported from the workspace package.

func CurrentWorkspaceName added in v0.0.7 

func CurrentWorkspaceName(root string) (WorkspaceName, bool, error)

CurrentWorkspaceName returns the active workspace preference.

func ParseWorkspaceName added in v0.0.7 

func ParseWorkspaceName(value string) (WorkspaceName, error)

ParseWorkspaceName validates and normalizes raw workspace names.

type WorkspaceRegistry added in v0.0.7 

type WorkspaceRegistry = workspace.Registry

Workspace domain types re-exported from the workspace package.

func LoadWorkspaceRegistry added in v0.0.7 

func LoadWorkspaceRegistry(root string) (WorkspaceRegistry, error)

LoadWorkspaceRegistry reads and validates the workspace registry file.

Source Files

View all Source files

Directories

Path Synopsis
Package branch defines local branch lifecycle operations.
 Package branch defines local branch lifecycle operations.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.