PointerForest

Rhizomatic traversal substrate. A network of lazy pointers, each pointing to a TimelineCompliant object that already exists elsewhere in the model. Nodes sleep until traversed. Any node can branch to any other node. Multiple roots. No forced hierarchy. Recency ranking is implicit in tNdx scalar comparison - no explicit rank field anywhere in the structure.

Package Declaration and Core Types

package pointerforest

import "sync"

// TimelineCompliant - the four-field compliance contract.
// Defined in package quantumseed; repeated here for package independence.
type TimelineCompliant interface {
    TIndex()    int64
    HolonPath() string
    Embedding() []float64
    Morphemes() []string
}

// ForestNode is one node in the pointer forest.
// wake: a closure that returns the underlying TimelineCompliant object.
// The object is not materialised until wake() is called.
// tNdx and holon are cached at insert time so the node can be
// compared and routed without waking the underlying object.
type ForestNode struct {
    wake     func() TimelineCompliant    // sleeps until called
    tNdx     int64                         // cached - compare without waking
    holon    string                        // cached - route without waking
    branches map[string]*ForestNode       // rhizomatic: any key → any node
    mu       sync.RWMutex                  // protects branches map
}

// PointerForest is the top-level structure.
// roots: holon path → root ForestNode for that Holon.
// index: insertion-ordered slice of all nodes - the recency index.
// mu:    protects roots map and index slice.
type PointerForest struct {
    roots map[string]*ForestNode
    index []*ForestNode
    mu    sync.RWMutex
}

// NewPointerForest returns an initialised, empty PointerForest.
func NewPointerForest() *PointerForest {
    return &PointerForest{
        roots: make(map[string]*ForestNode),
    }
}
      

The forest does not own the underlying data. Every ForestNode holds a closure - wake() - that reaches into whatever store holds the actual TimelineCompliant object (a QuantumSeed, a JSONL file, an in-memory map) and returns it. The forest is a traversal index over data it does not store. This separation is intentional: the forest can be rebuilt, compacted, or restructured without touching the underlying records.

ForestNode - Field Detail

wake

func() TimelineCompliant

Closure that materialises the underlying record. Called only when the caller needs the full object - embedding, full morpheme list. Not called for comparison or routing.

tNdx

int64

Cached TIndex value from the underlying record. Set at node insertion. Enables recency comparison and GhostInterval range queries without waking the node.

holon

string

Cached HolonPath value. Enables routing and partition filtering without waking the node. Used as the key in the PointerForest.roots map.

branches

map[string]*ForestNode

Outbound pointer map. Key is arbitrary - can be a holon path, a morpheme label, a tNdx string, or any application-defined route key. Any node can point to any other node. No topology is enforced.

sync.RWMutex

Protects concurrent read/write of the branches map. Allows multiple goroutines to traverse branches simultaneously while branch additions are serialised.

The Lazy Wake Pattern

The forest's defining property is deferred materialisation. A node exists in the forest - it has a tNdx, a holon path, outbound branches - but the underlying TimelineCompliant object it points to is not loaded until the caller explicitly calls node.Wake(). Until then, the node participates in traversal, comparison, and range queries at essentially zero cost.

Sleeping

Node inserted. tNdx and holon cached. wake() closure stored. Branches initialised empty. Underlying object not loaded. Participates in GhostInterval, routing, recency comparison.

→

Waking

Caller invokes node.Wake(). The wake() closure executes - fetches the underlying TimelineCompliant from its store. Result memoised on first call: subsequent Wake() calls return the cached object.

→

Awake

Full object available. Embedding vector accessible. Complete morpheme list accessible. Caller can traverse embedding space, feed into Clio, or inspect the full compliance contract.

// ForestNode.Wake - materialise the underlying record.
// Memoised: wake() closure is called at most once.
func (fn *ForestNode) Wake() TimelineCompliant {
    fn.mu.Lock()
    defer fn.mu.Unlock()

    if fn.live != nil {
        return fn.live   // already awake - return cached object
    }
    fn.live = fn.wake() // materialise once
    fn.wake = nil        // release closure - GC can collect captured refs
    return fn.live
}

// Insert adds a new node to the forest without waking any existing node.
// wakeFunc: closure that returns the record when called.
// The record's tNdx and holon are required up front for caching.
func (pf *PointerForest) Insert(
    tNdx  int64,
    holon string,
    wakeFunc func() TimelineCompliant,
) *ForestNode {

    node := &ForestNode{
        wake:     wakeFunc,
        tNdx:     tNdx,
        holon:    holon,
        branches: make(map[string]*ForestNode),
    }

    pf.mu.Lock()
    defer pf.mu.Unlock()

    // Register as root for this holon if no root exists yet
    if _, ok := pf.roots[holon]; !ok {
        pf.roots[holon] = node
    }
    pf.index = append(pf.index, node)
    return node
}
      

Why memoisation matters: in a long dialogue session the forest may hold thousands of nodes, but a given traversal path wakes only the nodes it actually visits. Nodes reachable by their holon path but not traversed in the current session remain sleeping indefinitely. Memory footprint scales with traversal depth, not forest size.

Rhizomatic Structure - No Forced Hierarchy

A rhizome has no privileged root. Any node is a valid entry point. The PointerForest implements this through the roots map and the unrestricted branches map on each node. Every Holon path that has had at least one node inserted becomes a root entry point. A node in the root.L.R.L partition can branch directly to a node in the root.R partition if the application establishes that branch. No topology is enforced by the forest itself.

// PointerForest - multiple roots, rhizomatic branches

roots map:

"root" → ForestNode{tNdx:1714521600, holon:"root"}

"root.L" → ForestNode{tNdx:1714521842, holon:"root.L"}

"root.L.R.L" → ForestNode{tNdx:1714522104, holon:"root.L.R.L"}

"root.R" → ForestNode{tNdx:1714521970, holon:"root.R"}

// branches - established by the application, not enforced by the forest

root.L.R.L.branches["next"] → root.L.R.R // sequential

root.L.R.L.branches["stereo"] → root.R // cross-partition jump

root.R.branches["ghost"] → ghost node // points into ghost interval

// index: insertion-ordered across all holons

index[0] tNdx=1714521600 index[1] tNdx=1714521842 index[2] tNdx=1714521970 ...

The roots map means there is no single tree with a single root that all nodes descend from. There are as many entry points as there are distinct Holon paths. A traversal may enter from any of them. The branches map on each node means a traversal can jump from any node to any other node that has been linked - including across Holon partitions, including backward in tNdx, including into ghost nodes. The forest does not validate branch targets.

// Root returns the root ForestNode for a given holon path.
// Returns nil if no node has been inserted under this holon.
func (pf *PointerForest) Root(holon string) *ForestNode {
    pf.mu.RLock()
    defer pf.mu.RUnlock()
    return pf.roots[holon]
}

// Branch adds a directed pointer from src to dst under the given key.
// Overwrites any existing branch under that key.
func (fn *ForestNode) Branch(key string, dst *ForestNode) {
    fn.mu.Lock()
    defer fn.mu.Unlock()
    fn.branches[key] = dst
}

// Follow traverses a branch by key. Returns nil if the branch does not exist.
// Does NOT wake the destination node - waking is the caller's decision.
func (fn *ForestNode) Follow(key string) *ForestNode {
    fn.mu.RLock()
    defer fn.mu.RUnlock()
    return fn.branches[key]
}
      

GhostInterval - Range Query Across the Full Forest

GhostInterval returns all nodes in the forest whose cached tNdx falls within a given range [lo, hi]. It operates on the global index slice - insertion-ordered, all nodes regardless of holon - and performs a linear scan. No nodes are woken during the scan. The returned slice contains sleeping nodes; the caller wakes only those it needs.

This is the primary cross-partition query operation. A caller with two ranked coordinates - the tNdx of a record in one Holon and the tNdx of a record in another - can query for everything that exists between them across the entire forest, regardless of which Holon it belongs to.

// rank axis: all nodes in insertion order

● ◌ ◌ ◌ ● ●

lo in range in range in range hi excluded

GhostInterval(lo, hi) → returns the three ◌ nodes. lo and hi are excluded by default.

Nodes returned are sleeping. Caller wakes as needed. No data loaded during the scan.

// GhostInterval returns all nodes with tNdx in the open interval (lo, hi).
// lo and hi are the bounding ranked coordinates - excluded from results.
// Nodes are returned in insertion order (ascending tNdx).
// No nodes are woken. Caller wakes selectively.
func (pf *PointerForest) GhostInterval(lo, hi int64) []*ForestNode {
    pf.mu.RLock()
    defer pf.mu.RUnlock()

    var result []*ForestNode
    for _, node := range pf.index {
        if node.tNdx > lo && node.tNdx < hi {
            result = append(result, node)
        }
    }
    return result
}

// GhostIntervalByHolon is GhostInterval filtered to a specific holon path.
// Returns only nodes in (lo, hi) whose cached holon matches the given path.
// Useful for intra-partition ghost queries without cross-partition noise.
func (pf *PointerForest) GhostIntervalByHolon(lo, hi int64, holon string) []*ForestNode {
    pf.mu.RLock()
    defer pf.mu.RUnlock()

    var result []*ForestNode
    for _, node := range pf.index {
        if node.tNdx > lo && node.tNdx < hi && node.holon == holon {
            result = append(result, node)
        }
    }
    return result
}
      

Complexity note: GhostInterval is O(n) in the total number of nodes in the forest. For forests with many thousands of nodes and frequent interval queries, consider maintaining a sorted secondary index by tNdx to enable binary search. The current implementation is optimised for simplicity and correctness over throughput.

Recency - tNdx Scalar Comparison

The index slice is insertion-ordered. Because records are inserted in capture order and tNdx is a monotonically increasing microsecond timestamp, the index is implicitly tNdx-sorted. Recency comparison between any two nodes requires only a scalar integer comparison of their cached tNdx fields. No explicit rank field. No sort step at query time.

// MostRecent returns the node with the highest tNdx across the whole forest.
func (pf *PointerForest) MostRecent() *ForestNode {
    pf.mu.RLock()
    defer pf.mu.RUnlock()
    if len(pf.index) == 0 { return nil }
    return pf.index[len(pf.index)-1]  // last inserted = highest tNdx
}

// MostRecentByHolon returns the most recent node in a given holon partition.
func (pf *PointerForest) MostRecentByHolon(holon string) *ForestNode {
    pf.mu.RLock()
    defer pf.mu.RUnlock()
    var latest *ForestNode
    for _, node := range pf.index {
        if node.holon == holon {
            latest = node  // insertion order ≡ tNdx order - last wins
        }
    }
    return latest
}

// IsMoreRecent: tNdx scalar comparison. No reference frame required.
func IsMoreRecent(a, b *ForestNode) bool {
    return a.tNdx > b.tNdx
}
      

HolonNode Integration

The PointerForest does not know about HolonNode directly - it operates on ForestNode and TimelineCompliant. The HolonNode integration is established by the application layer: when a HolonNode is instantiated, it registers a root entry in the PointerForest for its path, and each record it emits is inserted into the forest with a wake closure that reaches back into the HolonNode's record store.

// HolonNode registration pattern - called at HolonNode instantiation
func (hn *HolonNode) RegisterWithForest(pf *PointerForest) {
    // Insert the Holon's current Now Horizon record as the root entry point
    latest := hn.LatestRecord()
    pf.Insert(
        latest.TIndex(),
        latest.HolonPath(),
        func() TimelineCompliant { return latest },
    )
}

// AppendRecord - called each time a new Now is written to the Holon's TimeField.
// Inserts a sleeping node. wake closure captures the record by reference.
func (hn *HolonNode) AppendRecord(r TimelineCompliant, pf *PointerForest) {
    hn.records = append(hn.records, r)
    pf.Insert(r.TIndex(), r.HolonPath(), func() TimelineCompliant { return r })
}

// After Divide(), register both child Holons and link from the parent's
// most recent node to each child's root via named branches.
func RegisterDivision(
    pf    *PointerForest,
    left  *HolonNode,
    right *HolonNode,
    parentLatest *ForestNode,
) {
    left.RegisterWithForest(pf)
    right.RegisterWithForest(pf)

    lRoot := pf.Root(left.Path())
    rRoot := pf.Root(right.Path())

    parentLatest.Branch("divide.L", lRoot)
    parentLatest.Branch("divide.R", rRoot)
}
      

Full Method Summary

Method	Returns	Description
NewPointerForest()	*PointerForest	Constructor. Empty roots map and index slice.
Insert(tNdx, holon, wakeFunc)	*ForestNode	Add a sleeping node. Registers as holon root if none exists. Appends to index. Write-locked.
Root(holon)	*ForestNode	Root entry point for a given holon path. Nil if none. Read-locked.
MostRecent()	*ForestNode	Node with highest tNdx across the whole forest. Tail of the index. Read-locked.
MostRecentByHolon(holon)	*ForestNode	Most recent node in the given holon partition. Linear scan, last-wins. Read-locked.
GhostInterval(lo, hi)	[]*ForestNode	All nodes with tNdx in open interval (lo, hi). No nodes woken. Read-locked.
GhostIntervalByHolon(lo, hi, holon)	[]*ForestNode	GhostInterval filtered to a single holon partition. Read-locked.
ForestNode.Wake()	TimelineCompliant	Materialise the underlying record. Memoised - closure called at most once.
ForestNode.Branch(key, dst)	-	Establish a directed pointer from this node to dst under the given key. Write-locked on the node.
ForestNode.Follow(key)	*ForestNode	Traverse a branch by key. Nil if key not present. Does not wake the destination. Read-locked on the node.
IsMoreRecent(a, b)	bool	Package-level helper. Returns a.tNdx > b.tNdx. No lock needed - tNdx is immutable after insert.

The forest is the traversal layer. The store it indexes is documented in → QuantumSeed.

The Holarchy that registers its records into the forest at each mitotic division is in → Holarchy of Agency.

Full Go package index, import paths, and JSONL schema reference are in → Reference.