sptos-vecgraph

Kernel-resident vector and graph stores for SPTOS Cognition Kernel

Overview

sptos-vecgraph implements the Vector and Graph kernel objects from ADR-087 Section 4.3. Unlike conventional kernels, SPTOS makes vector stores and graph stores kernel-resident objects with capability protection and proof-gated mutations. Vector data lives in slab regions, HNSW index nodes are slab-allocated, and every mutation emits a witness attestation.

Key Features

• Kernel-resident vector store — Vectors stored in slab regions with co-located coherence metadata
• HNSW indexing — Hierarchical Navigable Small World graph for approximate nearest neighbor search
• Proof-gated mutations — No vector write or graph mutation succeeds without a valid proof
• SIMD distance functions — Cosine similarity, dot product, and Euclidean distance with SIMD acceleration
• Witness attestation — Every successful mutation emits a witness log entry for auditability
• Coherence tracking — Optional coherence scoring for vector/graph operations

Dependencies

Key internal dependencies:

• sptos-types — Vector/graph types (VectorKey, GraphHandle, CoherenceMeta)
• sptos-region — Slab-backed storage for vectors and HNSW nodes
• spt-coherence (optional) — Coherence scoring integration

Usage

use sptos_vecgraph::{KernelVectorStore, VectorStoreBuilder, ProofPolicy};
use sptos_types::{VectorKey, CapRights};

let store = VectorStoreBuilder::new(768, 10000)
    .with_proof_policy(ProofPolicy::standard())
    .build(backing)?;

let (data, meta) = store.vector_get(key, cap)?;

API Reference

Core Types

Type	Description
KernelVectorStore	Kernel-resident vector store with proof-gated writes
VectorStoreBuilder	Builder for configuring vector store dimensions and capacity
KernelGraphStore	Kernel-resident graph store for knowledge graph mutations
GraphStoreBuilder	Builder for configuring graph stores
HnswRegion	HNSW index backed by slab-allocated regions
ProofPolicy	Policy defining which proof tier is required for mutations
CoherenceTracker	Tracks coherence metadata for stored vectors
WitnessLog	Append-only log of mutation attestations