repository

package
v0.0.3 Latest Latest
Warning

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

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

Documentation ¶

Overview ¶

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.

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 (
	// 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 = errors.New("branch not found")
	// 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 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 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.

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

NewSeedRepository returns an in-memory repository initialized with the seed graph.

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

Source Files ¶

View all Source files

Directories ¶

Path Synopsis
Package branch defines local branch lifecycle operations.
 Package branch defines local branch lifecycle operations.
Package initialization exposes the repository initialization use case.
 Package initialization exposes the repository initialization use case.
Package integrity exposes the durable repository integrity-check use case.
 Package integrity exposes the durable repository integrity-check use case.
Package merge defines merge transaction lifecycle operations.
 Package merge defines merge transaction lifecycle operations.

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.