Reference · Go Package Index

Technical Reference

Go package index, import paths, JSONL TimeField schema, the four-field compliance contract, compliance checklist, and a cross-package method index. The canonical lookup point for the full implementation.

Go Package Index

Four packages constitute the complete Timeline Paradigm Go implementation. All packages are in the same module. Each is independently importable. The TimelineCompliant interface is defined in quantumseed and re-exported by the other packages for standalone use without import cycles.

// Module declaration - go.mod
module github.com/groupkos/timeline

go 1.22
      

quantumseed

github.com/groupkos/timeline/quantumseed

Concurrent rank-indexed time-series store. Category-keyed matrix. Ranked-Nth-occurrence address. Soviet Stereoscopic ghost-pattern extraction.

Layer 1

pointerforest

github.com/groupkos/timeline/pointerforest

Rhizomatic traversal substrate. Sleeping lazy pointers. Any node branches to any node. GhostInterval range query. No forced hierarchy.

Layer 1

clio

github.com/groupkos/timeline/clio

Markovian temporal operator. Iterates across TimeField partitions. Ghost morpheme extraction. Anticipatory forward seeding. IterateStereo for inter-Holon disparity.

Layer 2

holarchy

github.com/groupkos/timeline/holarchy

BST of HolonNode units. Mitotic binary division at efficacy threshold. Perfunctor path as BST address, partition key, and forward-conditioning signal.

Layer 2

Dependency graph

// Import dependencies - arrows show direction of import
// No import cycles.

holarchy     → imports →  pointerforest  → imports →  (stdlib only)
holarchy     → imports →  clio
holarchy     → imports →  quantumseed
clio          → imports →  quantumseed
clio          → imports →  pointerforest
quantumseed  → imports →  (stdlib only: sync, fmt, math)
pointerforest → imports → (stdlib only: sync)
      

JSONL TimeField Schema

The TimeField is an append-only JSONL file. One JSON object per line. Each line is a Now - a captured moment. The schema is the four-field compliance contract. Additional fields are permitted under a meta key and are ignored by all compliance-checking operations.

Field	Type	Description	Constraints
tNdx	int64	Ranked time index. Unix epoch in microseconds at moment of record creation. Scalar comparison of two tNdx values is recency ranking.	Monotonically increasing within a session. Unique across the file. Never zero.
holon	string	BST perfunctor path key. Dot-separated path from root. Simultaneously: BST address, partition key, and forward-conditioning signal for the next Now.	Non-empty. Valid path characters: `[a-zA-Z0-9._-]`. Root Holon is `"root"`. Stereo ghost prefix: `"stereo:"`.
embedding	[]float64	Forward-conditioned vector. Shaped toward the next Now Horizon turn by the embedding endpoint. May be empty (`[]`) if the async embedding fill has not yet completed.	All elements finite (no NaN, no Inf). Length consistent within a Holon partition. Unit-normalised for Hexatron captures.
morphemes	[]string	Category keys for QuantumSeed matrix indexing. What was active or detected at this Now. May be empty if no morphemes crossed the salience floor.	Each element non-empty. No duplicates within a single record. Values are application-defined strings.

Canonical record - dialogue endpoint

{
  "tNdx":      1714521600123456,
  "holon":     "root.L.R.L",
  "embedding": [0.0231, -0.4412, 0.8823, 0.1047],
  "morphemes": ["coherence", "ghost", "ranked-occurrence"]
}
      

Pending embedding - async fill not yet complete

{
  "tNdx":      1714521600987654,
  "holon":     "root.L.R.L",
  "embedding": [],
  "morphemes": ["horizon"]
}
      

Hexatron capture record

{
  "tNdx":      1714521600555111,
  "holon":     "hexatron/ses_a1b2c3/0042",
  "embedding": [0.0012, 0.0018, 0.4721, 0.0009],
  "morphemes": ["698Hz@-77.3dBV", "1047Hz@-81.1dBV"]
}
      

Session boundary record

{
  "tNdx":      1714525200000000,
  "holon":     "session/close",
  "embedding": [],
  "morphemes": [],
  "meta": { "event": "session_close", "duration_s": 3600 }
}
      

Write discipline: records are append-only. No line in the JSONL file is ever modified after write. The exception is the async embedding fill, which uses QuantumSeed.SetEmbedding() to update the in-memory object - the JSONL file itself is not modified. If durability of embedding vectors is required, flush a second write after the embedding fill completes.

TimelineCompliant Interface

The compliance contract is four methods. Any Go type that implements all four is a valid node in the PointerForest, a valid entry in a QuantumSeed matrix, and a valid record in the JSONL TimeField. The interface is the universal join point across all packages.

// TimelineCompliant - the four-field compliance contract.
// Defined in: github.com/groupkos/timeline/quantumseed
// Re-exported by: pointerforest, clio, holarchy
type TimelineCompliant interface {

    // TIndex returns the ranked time index.
    // Scalar comparison of two TIndex values IS recency ranking.
    // No additional rank field is needed anywhere in the system.
    TIndex() int64

    // HolonPath returns the BST perfunctor path key.
    // Simultaneously: BST address · partition key · forward-conditioning signal.
    // Stored directly in the JSONL record. No external registry required.
    HolonPath() string

    // Embedding returns the forward-conditioned vector.
    // May return nil or empty slice if the async fill is pending.
    // All cosine operations should guard against zero-length embedding.
    Embedding() []float64

    // Morphemes returns the category keys active at this Now.
    // Used as matrix keys in QuantumSeed. May be empty.
    Morphemes() []string
}

// Optional extension - implement to support async embedding fill.
type EmbeddingSetter interface {
    TimelineCompliant
    SetEmbedding(vec []float64)
}
      

Minimal concrete implementation

// TimelineRecord - concrete implementation of TimelineCompliant.
// Drop-in for dialogue records, Hexatron captures, forward seeds.
type TimelineRecord struct {
    TIndex_    int64
    HolonPath_ string
    Embedding_ []float64
    Morphemes_ []string
    mu         sync.RWMutex  // protects Embedding_ for async fill
}

func (r *TimelineRecord) TIndex()    int64     { return r.TIndex_ }
func (r *TimelineRecord) HolonPath() string    { return r.HolonPath_ }
func (r *TimelineRecord) Morphemes() []string  { return r.Morphemes_ }

func (r *TimelineRecord) Embedding() []float64 {
    r.mu.RLock()
    defer r.mu.RUnlock()
    return r.Embedding_
}

func (r *TimelineRecord) SetEmbedding(vec []float64) {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.Embedding_ = vec
}
      

Compliance Checklist

Use this checklist to verify a new record type or data source before integrating it with the Timeline Paradigm packages.

✓ 01
TIndex() returns int64 microsecond Unix epoch. Not milliseconds. Not nanoseconds. Not a sequence counter. The value must be directly comparable with timestamps from other Timeline Paradigm sources (dialogue records, Hexatron captures) for cross-source recency ranking to work.
✓ 02
TIndex() is monotonically increasing within a session. Two records written in the same session must have distinct, ordered TIndex values. If your source produces batch records, assign tNdx at write time, not at event time.
✓ 03
HolonPath() returns a non-empty, dot-delimited path string. Valid characters: [a-zA-Z0-9._-]. Root is "root". Hexatron path format is "hexatron/{sessionID}/{index}". Stereo ghost prefix is "stereo:" - this colon is the only valid exception to the dot-delimiter rule.
✓ 04
Embedding() is safe for concurrent read. If SetEmbedding() is supported, the implementation must guard with a sync.RWMutex or equivalent. Reads and async fills may occur simultaneously from different goroutines.
✓ 05
Embedding() returns nil or empty slice (not panic) before fill. All cosine operations in QuantumSeed and Clio guard against zero-length embeddings. A pending-fill record must not panic when Embedding() is called - it must return a safe zero value.
✓ 06
Embedding() values are finite. No NaN, no ±Inf. Cosine distance computations produce undefined results for non-finite vectors. Validate at fill time.
✓ 07
Morphemes() returns no duplicate strings within a single record. Duplicate morpheme keys would result in the same record being indexed twice under the same category in QuantumSeed, inflating OccurrenceCount and distorting ranked slices.
✓ 08
Record is treated as immutable after Insert() or AppendRecord(). Fields other than Embedding_ must not be mutated after a record has been registered with QuantumSeed or PointerForest. The tNdx and holon are cached at insert time; post-insert mutation of these fields will silently desync the cache.
✓ 09
Embedding vector length is consistent within a Holon partition. Clio's centroid computation assumes all embeddings in a partition have the same dimensionality. Mixed-length embeddings within a partition will produce incorrect cosine distances. Hexatron captures and dialogue records should use separate Holon namespaces if their embedding dimensions differ.
✓ 10
JSONL file is append-only. No line is modified after write. Session-close records mark batch boundaries. If the embedding flush is written to file, append a second record with the same tNdx and holon but with the embedding field populated - downstream consumers should use the last record for a given tNdx.

Cross-Package Method Index

Method	Package	Returns	Description
New()	quantumseed	*QuantumSeed	Initialised empty store.
Insert(r)	quantumseed	-	Append record under each morpheme key and to the all-index. Write lock.
SetEmbedding(tNdx, vec)	quantumseed	error	Async embedding fill by tNdx. Write lock.
NthOccurrence(cat, n)	quantumseed	TimelineCompliant, error	Direct rank address. O(1).
RankedSlice(cat, lo, hi)	quantumseed	[]TimelineCompliant	Rank window for a category.
OccurrenceCount(cat)	quantumseed	int	Length of the ranked slice for a category.
LatestN(cat, n)	quantumseed	[]TimelineCompliant	n most recent records for a category.
AllRecords()	quantumseed	[]TimelineCompliant	Full insertion-ordered record list. Shallow copy.
Categories()	quantumseed	[]string	All category keys. Sorted snapshot.
RecordsByTNdx(lo, hi)	quantumseed	[]TimelineCompliant	All records with TIndex in [lo, hi].
GetSovietStereoscopic(catA, catB, threshold)	quantumseed	[]GhostPattern	Ghost-pattern extraction from disparity field between two category streams.
NewPointerForest()	pointerforest	*PointerForest	Initialised empty forest.
Insert(tNdx, holon, wake)	pointerforest	*ForestNode	Add sleeping node. Register root if new holon.
Root(holon)	pointerforest	*ForestNode	Root entry point for a holon path.
GhostInterval(lo, hi)	pointerforest	[]*ForestNode	All nodes with tNdx in open interval (lo, hi). No nodes woken.
GhostIntervalByHolon(lo, hi, holon)	pointerforest	[]*ForestNode	GhostInterval filtered to one holon partition.
MostRecent()	pointerforest	*ForestNode	Node with highest tNdx across the whole forest.
MostRecentByHolon(holon)	pointerforest	*ForestNode	Most recent node in a holon partition.
ForestNode.Wake()	pointerforest	TimelineCompliant	Materialise the underlying record. Memoised.
ForestNode.Branch(key, dst)	pointerforest	-	Establish a directed pointer to dst under key.
ForestNode.Follow(key)	pointerforest	*ForestNode	Traverse a branch. Does not wake destination.
Iterate(holon)	clio	[]*Ghost	Full Markovian iteration: collect → transitions → extract → filter → seed → yield.
IterateStereo(holonL, holonR)	clio	[]*Ghost	Inter-partition ghost extraction from the disparity field between two Holons.
extractGhosts(records, path)	clio	[]*Ghost	Find ghost morphemes in intervals between adjacent ranked records.
seedAnticipation(latest)	clio	-	Construct forward seed from transition matrix and current Now Horizon.
HolonNode.Divide()	holarchy	HolonNode, HolonNode, error	Mitotic binary division. Returns left and right children. Parent retired.
HolonNode.RegisterWithForest(pf)	holarchy	-	Insert current Now Horizon record as root entry in the PointerForest.
HolonNode.AppendRecord(r, pf)	holarchy	-	Append a new Now record to the Holon's TimeField and the PointerForest.
RegisterDivision(pf, left, right, parentLatest)	holarchy	-	Register both children in the forest and link from parent via divide.L / divide.R branches.

Error Types

// Sentinel errors - comparable with errors.Is()

var (
    // quantumseed
    ErrCategoryNotFound    = errors.New("quantumseed: category not found")
    ErrRankOutOfBounds     = errors.New("quantumseed: rank index out of bounds")
    ErrTNdxNotFound        = errors.New("quantumseed: tNdx not found in all-index")
    ErrEmbeddingSetterNoop = errors.New("quantumseed: record does not implement EmbeddingSetter")

    // pointerforest
    ErrHolonNotRegistered  = errors.New("pointerforest: holon not registered as root")
    ErrBranchNotFound      = errors.New("pointerforest: branch key not found")

    // holarchy
    ErrInsufficientRecords = errors.New("holarchy: insufficient records to divide")
    ErrAlreadyDivided      = errors.New("holarchy: holon has already been divided")

    // clio
    ErrEmptyPartition      = errors.New("clio: holon partition is empty")
    ErrVocabNotInitialised = errors.New("clio: morpheme vocabulary not initialised")
)
      

Hexatron Output - Field Quick Reference

Hexatron captures are TimelineCompliant objects. Their field values follow the same schema as dialogue records with the conventions below. Full engineering specification at → Apparatus.

Field	Type	Hexatron convention	Example
tNdx	int64	Unix epoch microseconds at ADC capture trigger. Same axis as dialogue records.	`1714521600555111`
holon	string	`hexatron/{sessionID}/{captureIndex}`. sessionID is a short random token per session. captureIndex is zero-padded decimal.	`"hexatron/ses_a1b2c3/0042"`
embedding	[]float64	Baseline-corrected, unit-normalised FFT magnitude spectrum. Length = window_samples / 2. Typically 2048 or 8192 elements.	`[0.0012, ..., 0.4721, ...]`
morphemes	[]string	Above-threshold spectral peaks outside the primary Larmor window. Format: `{freq}Hz@{amplitude}dBV`. Empty if no peaks exceed threshold.	`"698Hz@-77.3dBV"`

Code documentation: → QuantumSeed · → PointerForest · → Clio · → Holarchy

Engineering specification: → Apparatus

Lab notebook and engineering register: → Dispatch