graph

type Algorithm[K comparable, P float32 | float64] interface {
	Run(g Graph[K, P]) (AlgorithmResult, error)
}

type AlgorithmResult interface {
}

type BFS[K comparable, P float32 | float64] struct {
	// contains filtered or unexported fields
}

type Direction int

type Entity[K comparable] interface {
	Node[K]

	GetValue() string
}

type ExcessTraversal[K cmp.Ordered, P float32 | float64] struct {
	// contains filtered or unexported fields
}

type Fact[K comparable] struct {
	NodeAttributes
	Hasher hash.Hasher[K, string] `json:"-"`
}

type Graph[K comparable, P float32 | float64] interface {
	GetHasher() hash.Hasher[K, string]

	// Get returns the node stored under key, or nil if absent.
	Get(key K) Node[K]

	// Set inserts a new node, deriving its key via the graph's hash
	// function.
	Set(node Node[K]) error

	// Put replaces the node stored under key with the given node.
	Put(key K, node Node[K]) error

	// Delete removes the node (and, by extension, its index entries and
	// incident relationships).
	Delete(node Node[K]) error

	// GetVectorIndex returns the graph's vector (semantic) index, keyed
	// by node key and storing embedding vectors of precision P.
	GetVectorIndex() index.VectorIndex[K, P]

	// GetTextIndex returns the graph's full-text search index.
	GetTextIndex() index.TextIndex[K, P]

	// MergeFrom merges the contents of g into this graph: nodes,
	// relationships and index entries. Nodes with colliding keys are
	// resolved by the implementation.
	MergeFrom(g Graph[K, P])

	// Copy returns a deep copy of the graph, independent of the
	// original: mutating one never affects the other.
	Copy() Graph[K, P]

	Nodes() map[K]Node[K]

	// AdjacencyMap returns the outgoing-edge view of the graph:
	// AdjacencyMap()[from][to] is the relationship from -> to.
	AdjacencyMap() map[K]map[K]K

	// PredecessorMap returns the incoming-edge view of the graph:
	// PredecessorMap()[to][from] is the relationship from -> to. It is
	// the transpose of AdjacencyMap and serves reverse traversal.
	PredecessorMap() map[K]map[K]K

	// Neighbours returns the keys adjacent to key in either direction
	// (successors and predecessors), in unspecified order. Unlike
	// AdjacencyMap/PredecessorMap it copies no more than one node's edge
	// rows, so a source-rooted traversal can read a single node's
	// neighbourhood without cloning the entire edge set on every call.
	Neighbours(key K) []K

	// Order returns the number of entities (vertices) in the graph.
	Order() int

	// Size returns the number of relationships (edges) in the graph.
	Size() int

	// Stats returns a point-in-time snapshot of the graph's shape.
	Stats() GraphStats

	// Search runs a hybrid query over the graph and returns matching
	// nodes alongside their ranking scores and the contribution records
	// the scores were folded from (parallel slices, ordered best-first,
	// at most top entries), plus the query's background rate — the one
	// query-global observation the scoring fold used, which explain
	// serializes so a client can recompute every score from its payload.
	// A caller that only wants ranked hits discards both.
	//
	// All criteria are optional and combine to narrow the result:
	//   - keywords: full-text terms matched against the text index
	//   - vector:   query embedding for nearest-neighbor search; nil
	//               (or empty) skips the vector index
	//   - topics:   restrict results to facts tagged with these topics
	//   - entities: restrict results to facts involving these entities
	//   - depth:    selects the retrieval lane. 0 skips the anchor
	//               traversal and ranks by seed mass alone (the floor; the
	//               fast, text-only lane). 1 and 2 both run the one
	//               anchor-mediated round and differ only in how much
	//               above-chance evidence an anchor needs to transmit: 1 is
	//               the precision lane, 2 admits at the plain fair share for
	//               maximum recall. It does not iterate
	//   - top:      maximum number of results returned
	//   - since:    inclusive lower time bound; zero value = unbounded
	//   - until:    exclusive upper time bound; zero value = unbounded
	Search(keywords []string, vector containers.Vector[K, P], topics []string, entities []string, depth int, top int, since time.Time, until time.Time) ([]*Node[K], []P, [][]scoring.Contribution[K, P], P)

	// RLock acquires the lock for reading.
	RLock()

	// Lock acquires the lock for writing.
	Lock()

	// RUnlock releases a read lock.
	RUnlock()

	// Unlock releases a write lock.
	Unlock()
}

type GraphStats struct {
	Order   int `json:"order"`   // number of entities (vertices)
	Size    int `json:"size"`    // number of relationships (edges)
	Nodes   int `json:"nodes"`   // total stored nodes
	Vectors int `json:"vectors"` // total vectors indexed
	// ForestEntries is how many entries the vector forest holds (live vectors
	// plus garbage awaiting compaction); bounded by the index's flush factor
	// times Vectors. 0 for index implementations without a forest.
	ForestEntries int `json:"forest_entries"`
}

type InMemoryGraph[K ~uint64, P float32 | float64] struct {
	// contains filtered or unexported fields
}

type IsAbout[K comparable] struct {
	Fact  *Fact[K]
	Topic *Topic[K]
	NodeAttributes

	Hasher hash.Hasher[K, string]
}

type Mentions[K comparable] struct {
	Fact        *Fact[K]
	NamedEntity *NamedEntity[K]
	NodeAttributes

	Hasher hash.Hasher[K, string]
}

type NamedEntity[K comparable] struct {
	NodeAttributes

	Hasher hash.Hasher[K, string] `json:"-"`
}

type Node[K comparable] interface {
	hash.Hashable[K, string]

	Key() K
	GetValue() string
	GetTimestamp() time.Time
	GetAttributes() *NodeAttributes
}

type NodeAttributes struct {
	Value     string
	Timestamp time.Time
}

type PageRank[K comparable, P float32 | float64] struct {
	// contains filtered or unexported fields
}

type Ranking[K comparable, P float32 | float64] interface {
	Algorithm[K, P]
	// contains filtered or unexported methods
}

type RankingResult[K comparable, P float32 | float64] struct {
	AlgorithmResult

	// Scores maps each vertex to its computed score.
	Scores map[K]P
}

type Relationship[K comparable] interface {
	Node[K]

	Source() *Entity[K]
	Target() *Entity[K]
}

type Topic[K comparable] struct {
	ID K
	NodeAttributes

	Hasher hash.Hasher[K, string] `json:"-"`
}

type Traversal[K comparable, P float32 | float64] interface {
	Algorithm[K, P]

	// Sets the traversal source
	SetSource(source K)

	// Clone returns a fresh traversal with the same configuration but no
	// per-run state, so each walk can set its own source and run on its own
	// instance instead of mutating a shared one.
	Clone() Traversal[K, P]
	// contains filtered or unexported methods
}

type TraversalResult[K comparable] struct {
	AlgorithmResult
	// Order lists the vertices in the order they were first visited.
	Order []K

	// Parent maps each visited vertex to the vertex it was discovered from,
	// forming the traversal tree. The source maps to its own key.
	Parent map[K]K

	// Parents maps each visited vertex to every vertex it was reached through
	// at the previous depth. Parent keeps the canonical (first-in-Order) entry
	// for tree-shaped consumers; Parents carries the full incidence, because a
	// member reached through two of the source's anchors is two observations,
	// not one. Tree-shaped traversals may leave it nil.
	Parents map[K][]K

	// Depth maps each visited vertex to its hop distance from the source.
	Depth map[K]int
}