route

Documentation

Overview

Package route holds the daemon's IVF centroid set and the plaintext cluster assignment used to route inserts. runed never dials the index engine: the set arrives via the SetCentroids RPC (relayed runespace → console → rune-mcp → runed) and is cached on disk so a restart does not need a re-push. Assignment must agree byte-for-byte with the engine's insert routing: max inner product over l2-normalized vectors, ties to the lowest id (mirrors runespace-go-sdk clustering).

Index

• func ComputeVersion(s *CentroidSet) string
• type CentroidSet
  • func Load(dir string) (*CentroidSet, error)
  • func (s *CentroidSet) Assign(vec []float32) uint32
  • func (s *CentroidSet) Persist(dir string) error
  • func (s *CentroidSet) Validate(wantDim int) error
  • func (s *CentroidSet) VerifyVersion() error

Functions

func ComputeVersion

func ComputeVersion(s *CentroidSet) string

ComputeVersion recreates the engine's content hash over the set: sha256 of dim, nlist, preset, then every centroid's float32 bits in id order (little-endian). MUST stay byte-identical to runespace's computeVersion (runespace/internal/cluster/centroid.go) — that equality is what lets runed verify a relayed or cached set against the version the engine minted.

Types

type CentroidSet

type CentroidSet struct {
	Version string
	Dim     int
	Preset  string
	Vectors [][]float32
}

CentroidSet is an immutable snapshot of the engine's IVF centroid set. Vectors[i] is cluster i's centroid (id order); Version is the set's content hash and travels with every routed assignment so the engine can reject routing done against a stale set. Preset is the evi preset the set was trained for — a Version-hash ingredient, so carrying it is what makes local recomputation (VerifyVersion) possible.

func Load

func Load(dir string) (*CentroidSet, error)

Load reads a previously persisted set. A missing cache returns (nil, fs.ErrNotExist-wrapped error); a corrupt cache returns an error and the caller should discard it and wait for the next SetCentroids push. Corruption covers both shapes: a broken gob (decode error) and — the insidious case — intact gob framing around flipped content bytes, which only the §9.2 C5 hash recomputation can see.

func (*CentroidSet) Assign

func (s *CentroidSet) Assign(vec []float32) uint32

Assign returns the cluster id whose centroid has the highest inner product with vec. vec must be l2-normalized — runed embeddings already are (llama.cpp last-pooling normalizes unconditionally). Ties resolve to the lowest id, matching the SDK/engine metric exactly.

func (*CentroidSet) Persist

func (s *CentroidSet) Persist(dir string) error

Persist writes the set atomically to dir (temp + rename), so a torn write never produces a half-cache. Best-effort semantics are the caller's call.

func (*CentroidSet) Validate

func (s *CentroidSet) Validate(wantDim int) error

Validate reports whether the set is internally consistent and matches the embedding dimension the daemon serves.

func (*CentroidSet) VerifyVersion

func (s *CentroidSet) VerifyVersion() error

VerifyVersion recomputes the content hash and compares it to the carried Version — the integrity gate at the set's two entry points (SetCentroids receipt, disk-cache load). An empty Preset means the sender predates the preset relay: the hash cannot be recreated without that ingredient, so verification is skipped (legacy behavior, trust the tag).