Spock is organized as a layered system where each layer depends only on the layers below it. This ensures testability, modularity, and clear separation of concerns.
┌─────────────────────────────────────────────────────────────┐
│ Public API Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │EngineFactory│ │ SessionApi │ │ VizApi │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Session & Theory Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │SessionManager│ │ TheoryStore │ │TheoryVersion│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ DSL Engine Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Tokenizer │ │ Parser │ │ Executor │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ │
│ │ DepGraph │ │
│ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Kernel Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ VectorSpace │ │PrimitiveOps │ │NumericKernel│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Support Layer │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Config │ │ TraceLogger │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
The foundation of Spock. Manages hypervector storage and provides primitive geometric operations.
| VectorSpace | Creates and manages Float32Array hypervectors. Provides createVector, cloneVector, dot, norm, normalise. |
| PrimitiveOps | Implements kernel verbs: Add, Bind, Negate, Distance, Move, Modulate. |
| NumericKernel | Handles numeric values with units: AddNumeric, MulNumeric, DivNumeric, AttachUnit. |
Parses and executes SpockDSL scripts with dependency-aware topological evaluation.
| Tokenizer | Splits DSL text into tokens, strips comments, tracks line numbers for error reporting. |
| Parser | Converts tokens to AST. Validates macro headers, statement forms, and SSA discipline. |
| DependencyGraph | Builds DAGs from statement references and computes topological execution order. |
| Executor | Executes scripts and macros, dispatches to kernel operations, produces DSL traces. |
Manages persistent theories and temporary sessions with symbol resolution.
| TheoryStore | Loads/saves theories from .spock/theories/ folder. Handles persistence and metadata. |
| TheoryVersioning | Implements BranchTheory and MergeTheory for in-memory theory versioning. |
| SessionManager | Creates sessions, manages symbol tables, handles theory overlays via UseTheory. |
External interface for applications, LLMs, and visualization clients.
| EngineFactory | Main entry point: createSpockEngine(options). Wires up configuration and default theories. |
| SessionApi | High-level methods: learn, ask, prove, explain, plan, solve, summarise. |
| VizApi | HTTP/WebSocket endpoints for concept projections and reasoning trajectory visualization. |
SessionApi method