QuantumSeed

Concurrent rank-indexed time-series store. Accepts any TimelineCompliant object. Indexes it by category key and ranked occurrence. Provides direct O(1) address to the Nth occurrence of any category. Extracts Soviet Stereoscopic ghost patterns from the rank-disparity field between two category streams. Safe for concurrent read and write via sync.RWMutex.

Package Declaration and Core Type

package quantumseed

import (
    "sync"
    "fmt"
    "math"
)

// TimelineCompliant is the four-field compliance contract.
// Any object implementing this interface is a valid QuantumSeed entry.
type TimelineCompliant interface {
    TIndex()    int64      // ranked time index - scalar comparison IS recency
    HolonPath() string     // BST perfunctor path key
    Embedding() []float64  // forward-conditioned vector
    Morphemes() []string   // category keys for matrix indexing
}

// QuantumSeed is the rank-indexed store.
// matrix: category → ordered slice of TimelineCompliant records.
// Each slice is the ranked occurrence history for that category.
// index[N] is the (N+1)th occurrence. Direct address, no scan.
type QuantumSeed struct {
    mu      sync.RWMutex
    matrix  map[string][]TimelineCompliant  // category → ranked slice
    all     []TimelineCompliant             // insertion-ordered full record list
}

// New returns an initialised, empty QuantumSeed.
func New() *QuantumSeed {
    return &QuantumSeed{
        matrix: make(map[string][]TimelineCompliant),
    }
}
      

The core data structure is straightforward: a map from category string to a slice of records, ordered by insertion sequence. Because TimelineCompliant.TIndex() is monotonically increasing and records are appended in capture order, the slice is implicitly tNdx-sorted without an explicit sort step. The Nth element of matrix["coherence"] is the (N+1)th occurrence of the "coherence" category - directly addressable as matrix["coherence"][N].

The all slice maintains insertion order across all categories, providing a global recency index. This is the TimeField view: every record regardless of category, in the order it was captured.

Category-Keyed Matrix - Internal Structure

When a record is inserted, its Morphemes() slice provides the category keys. The record is appended to the ranked slice for each category it belongs to. A record with three morphemes - ["coherence", "ghost", "horizon"] - is inserted into three category slices simultaneously. It occupies a rank position in each.

// category-keyed matrix after several inserts

matrix = {

"coherence": [

rank 0 → {tNdx:1714521600, holon:"root", morphemes:["coherence","ghost"]}

rank 1 → {tNdx:1714521842, holon:"root.L", morphemes:["coherence","horizon"]}

rank 2 → {tNdx:1714522104, holon:"root.L.R", morphemes:["coherence"]}

"ghost": [

rank 0 → {tNdx:1714521600, holon:"root", morphemes:["coherence","ghost"]}

rank 1 → {tNdx:1714521970, holon:"root.R", morphemes:["ghost","ranked-occ"]}

"horizon": [

rank 0 → {tNdx:1714521842, holon:"root.L", morphemes:["coherence","horizon"]}

}

// NthOccurrence("coherence", 1) → rank 1 record. O(1). No scan.

// NthOccurrence("ghost", 0) → rank 0 record. Same record as coherence[0].

// Record appears in multiple slices. Single underlying object.

Memory model: Records are stored by reference (pointer) in the matrix slices. A record that appears in three category slices has three pointers to one object - not three copies. The all slice also holds a pointer to the same object. Mutation of a record after insertion is not supported. Records are treated as immutable once written.

Concurrency Model - RWMutex

QuantumSeed is designed for concurrent access: a dialogue endpoint writing new records in real time and an embedding endpoint filling the embedding field asynchronously on the same record are the canonical concurrent writers. Multiple goroutines may read simultaneously. Write operations are serialised.

Concurrent reads

Any number of goroutines may call read methods simultaneously. RLock() is held for the duration of the read and released before return.

Serialised writes

Insert() acquires the full write lock. No read may proceed during an insert. Inserts are expected to be fast - append only, no sort.

Embedding fill path

The embedding endpoint calls SetEmbedding(tNdx, vec) - a write-locked operation that locates the record by tNdx and updates its embedding in place. The record pointer in the matrix slices reflects the update immediately.

// Insert appends a record to the matrix under each of its morpheme keys.
// Also appended to the global all-records index.
// Write-locked for the duration of the append operations.
func (qs *QuantumSeed) Insert(r TimelineCompliant) {
    qs.mu.Lock()
    defer qs.mu.Unlock()

    for _, cat := range r.Morphemes() {
        qs.matrix[cat] = append(qs.matrix[cat], r)
    }
    qs.all = append(qs.all, r)
}

// SetEmbedding locates the record with the given tNdx in the all-index
// and calls its SetEmbedding method. Used by the async embedding endpoint.
// Write-locked: embedding fill is a mutation.
func (qs *QuantumSeed) SetEmbedding(tNdx int64, vec []float64) error {
    qs.mu.Lock()
    defer qs.mu.Unlock()

    for _, r := range qs.all {
        if r.TIndex() == tNdx {
            if s, ok := r.(EmbeddingSetter); ok {
                s.SetEmbedding(vec)
                return nil
            }
        }
    }
    return fmt.Errorf("quantumseed: tNdx %d not found", tNdx)
}
      

Ranked Access - Core Query Methods

The primary value of QuantumSeed over a plain append-log is direct rank address. These methods do not scan. They access by slice index. All are read-locked and safe for concurrent call.

Method	Returns	Description
NthOccurrence(cat, n)	TimelineCompliant, error	The (n+1)th record in the ranked slice for category `cat`. n=0 is the first occurrence. Returns error if n ≥ len(slice).
RankedSlice(cat, lo, hi)	[]TimelineCompliant	All records for `cat` at rank positions lo..hi inclusive. Equivalent to `matrix[cat][lo:hi+1]`. Returns empty slice if out of range.
OccurrenceCount(cat)	int	Number of times `cat` has been recorded. Length of its ranked slice. O(1).
LatestN(cat, n)	[]TimelineCompliant	The n most recent records for `cat`, in descending tNdx order. Tail of the ranked slice, reversed.
AllRecords()	[]TimelineCompliant	Full insertion-ordered record list across all categories. A shallow copy - the returned slice is safe to iterate outside the lock.
Categories()	[]string	All category keys present in the matrix. Sorted lexicographically. Snapshot at time of call.
RecordsByTNdx(lo, hi)	[]TimelineCompliant	All records from the global all-index whose TIndex falls in [lo, hi]. Linear scan of `all`. Use for ghost interval queries across the full store.

// Ranked access examples

// Direct rank address - O(1)
third, err := qs.NthOccurrence("coherence", 2)  // 3rd occurrence (0-indexed)

// Rank window - O(1) slice operation
window := qs.RankedSlice("coherence", 3, 8)  // ranks 3 through 8 inclusive

// Recency - last 5 records for a category
recent := qs.LatestN("ghost", 5)

// Ghost interval query - all records between two tNdx values
// This is the QuantumSeed-level equivalent of PointerForest.GhostInterval()
interval := qs.RecordsByTNdx(1714521600, 1714522000)
      

Soviet Stereoscopic Ghost-Pattern Extraction

The stereoscopic operation takes two category streams - two ranked slices from the matrix - and extracts the ghost patterns that exist in the rank-disparity field between them. A ghost pattern is a record (or a computed midpoint between records) that is equidistant in embedding space from the centroids of both streams. It belongs fully to neither; it emerges from the disparity between them.

The operation is named for the Soviet-lineage source of the underlying theorem: two slightly displaced views of the same field, neither containing the depth information alone, the depth emerging from their parallax. In QuantumSeed, the two "views" are two ranked category streams. The "depth" is the set of records or computed points that are most equidistant from both streams' embedding centroids.

// GetSovietStereoscopic extracts ghost patterns from the disparity field
// between two category streams.
// catA, catB: the two category keys to compare.
// threshold:  minimum equidistance score to qualify as a ghost pattern.
func (qs *QuantumSeed) GetSovietStereoscopic(
    catA, catB string,
    threshold float64,
) []GhostPattern {

    qs.mu.RLock()
    defer qs.mu.RUnlock()

    sliceA := qs.matrix[catA]
    sliceB := qs.matrix[catB]
    if len(sliceA) == 0 || len(sliceB) == 0 {
        return nil
    }

    // Compute embedding centroid for each stream
    centroidA := centroid(sliceA)
    centroidB := centroid(sliceB)

    // Disparity midpoint in embedding space
    mid := midpoint(centroidA, centroidB)

    // Score every record in the all-index against the midpoint.
    // GhostScore = proximity to mid × equidistance from A and B centroids.
    var ghosts []GhostPattern
    for _, r := range qs.all {
        emb := r.Embedding()
        if len(emb) == 0 {
            continue  // skip records pending embedding fill
        }
        eqScore := equidistanceScore(emb, centroidA, centroidB)
        proxScore := 1.0 - cosineDistance(emb, mid)
        ghostScore := eqScore * proxScore

        if ghostScore >= threshold {
            ghosts = append(ghosts, GhostPattern{
                Record:     r,
                GhostScore: ghostScore,
                CatA:       catA,
                CatB:       catB,
            })
        }
    }

    // Sort descending by GhostScore
    sortByGhostScore(ghosts)
    return ghosts
}
      

GhostPattern struct

Record

TimelineCompliant

The actual record that scored above threshold. Its tNdx, holon, and morphemes are the ghost's provenance.

GhostScore

float64

Combined equidistance × proximity score. Range [0.0, 1.0]. Higher = deeper in the disparity field between the two category streams.

CatA

string

First category stream used in the stereoscopic operation. Retained for provenance.

CatB

string

Second category stream. The ghost pattern belongs to neither CatA nor CatB - it sits between them.

Helper functions

// centroid: mean embedding vector across a ranked slice.
func centroid(records []TimelineCompliant) []float64 {
    // Sum all embedding vectors, divide by count. Skips zero-length embeddings.
}

// midpoint: element-wise mean of two equal-length vectors.
func midpoint(a, b []float64) []float64

// cosineDistance: 1 - cosine_similarity(a, b). Range [0.0, 2.0].
// cosineDistance = 0.0 means identical direction. = 1.0 means orthogonal.
func cosineDistance(a, b []float64) float64 {
    dot, normA, normB := 0.0, 0.0, 0.0
    for i := range a {
        dot   += a[i] * b[i]
        normA += a[i] * a[i]
        normB += b[i] * b[i]
    }
    if normA == 0 || normB == 0 { return 1.0 }
    return 1.0 - (dot / (math.Sqrt(normA) * math.Sqrt(normB)))
}

// equidistanceScore: how equal are the distances from v to a and b?
// Score = 1 - abs(dist(v,a) - dist(v,b)) / (dist(v,a) + dist(v,b)).
// Score = 1.0 when perfectly equidistant. Score → 0.0 when skewed to one side.
func equidistanceScore(v, a, b []float64) float64 {
    dA := cosineDistance(v, a)
    dB := cosineDistance(v, b)
    if dA + dB == 0 { return 1.0 }
    return 1.0 - math.Abs(dA - dB) / (dA + dB)
}
      

Full Method Summary

Method	Lock	Description
New()	-	Constructor. Returns initialised *QuantumSeed with empty matrix and all-index.
Insert(r)	Write	Append record to matrix under each morpheme key and to the all-index.
SetEmbedding(tNdx, vec)	Write	Locate record by tNdx in all-index. Set its embedding vector. Used by async embedding endpoint.
NthOccurrence(cat, n)	Read	Direct rank address. Returns the (n+1)th record for category cat.
RankedSlice(cat, lo, hi)	Read	Rank window [lo, hi] for category cat. O(1) slice operation.
OccurrenceCount(cat)	Read	Number of records indexed under category cat.
LatestN(cat, n)	Read	n most recent records for cat, descending tNdx order.
AllRecords()	Read	Full insertion-ordered record list. Shallow copy, safe outside lock.
Categories()	Read	All category keys in the matrix. Lexicographically sorted snapshot.
RecordsByTNdx(lo, hi)	Read	All records with TIndex in [lo, hi]. Linear scan of all-index.
GetSovietStereoscopic(catA, catB, threshold)	Read	Ghost-pattern extraction from the embedding-space disparity field between two category streams. Returns []GhostPattern sorted descending by GhostScore.

QuantumSeed is the store. The traversal substrate that operates on the same records is in → PointerForest.

The full Go package index with import paths and compliance checklist is in → Reference.

For the theoretical framework underlying the ranked-occurrence design - → Paradigm.