Kalika Domain - Architecture

Architectural overview of Kalika, Oshun's scientific-research platform: the symbolic foundation (@kalika/core), the Rust compute kernels, the live TypeScript service plane, the large mathematics/physics/materials library set, and the honest seams between what is wired together today and what is built-but-not-yet-connected (apps/kalika/*, libs/kalika/*).

Kalika is Oshun's scientific research platform. Where the consumer domains (Saraswati, Brigid, Cybele, Airmid, Demeter, Maat) make domain decisions on top of validated knowledge, Kalika owns the layer underneath them: the symbolic-algebra representation, the provenance model, the compute kernels, the reactive research notebooks, the autonomous research agents, and a broad library of mathematics, theoretical-physics, and materials-science code.

The problem Kalika is built around is the reproducibility-and-auditability gap in computational science. A bare number is not a scientific result; what matters is the chain of reasoning, the assumptions made, the units, the tolerance, and whether the answer was formally proven or merely estimated numerically. Kalika threads those requirements through the whole stack: the ProvenResult<T> type in @kalika/core carries a derivation chain and a verification status; the notebook model captures seeds and environment under a kalika.reproducibility key; the compute queue content-hashes tasks into a cacheKey so identical work is served identically.

The workspace is large — roughly 93 TypeScript library packages, 6 applications, two Rust crate workspaces (cas-engine, numerical-engine), and a Python SDK, totalling on the order of 2,550 tracked files. That breadth is real, but it is unevenly integrated, and the most important thing to understand about Kalika's architecture is which pieces are connected to which. This page is honest about those seams.

Two compute substrates, loosely coupled#

The single most load-bearing fact about Kalika is that it contains two parallel symbolic/numeric stacks that are not yet wired to each other:

1. The Rust kernels — kalika-cas-core (a deep computer-algebra kernel) and kalika-numerical-engine-core (a deep dense/sparse linear-algebra kernel). Both are genuinely substantial, benchmarked Rust, and both ship napi-rs and/or wasm-bindgen bridge crates. But no TypeScript package imports them at runtime. @kalika/cas-engine is listed as a dependency by zero of the 93 libraries; @kalika/numerical-engine by one. The strings '@kalika/cas-engine' that appear in libs/kalika/calculus/src/ and libs/kalika/notebooks/src/reproducibility.ts are backend-name labels and metadata, not imports.

2. The live TypeScript engine — the compute service, the SDK, and the notebook kernel run on a hand-written TypeScript implementation: @kalika/core's Expr AST and provenance types, a string-based symbolic engine (apps/kalika/svc-compute/src/engine.ts), real numeric linear algebra written directly in TypeScript, and @kalika/tensor-networks for einsum. This is the path a request actually travels today.

Both substrates are real. The Rust kernel is not a stub — kalika-cas-core implements the Risch algorithm, Rubi rules, Gruntz limits, Gosper/Zeilberger summation, Buchberger/F4/F5 Gröbner bases, and certified ball arithmetic (libs/kalika/cas-engine/crates/kalika-cas-core/src/calculus.rs, sparse_polynomial.rs). But it is built-and-benchmarked, not yet bridged. The honest framing throughout this page is: the Rust kernels are a ready compute substrate awaiting integration; the TypeScript engine is the shipping one and is deliberately lighter-weight.

Foundation: @kalika/core and @kalika/utils#

@kalika/core (libs/kalika/core/) is the genuine spine of the platform's service stack. It defines:

• The Expr symbolic AST (src/expr.ts) — a discriminated union over a kind field with 20 node kinds (IntegerLiteral, RationalLiteral, RealLiteral, Symbol, FunctionApp, BinaryOp, Derivative, Integral, Matrix, Tensor, Equation, Proof, Undefined, …). All fields are readonly; integers/rationals are stored as bigint and reals as decimal strings so exact arithmetic is never corrupted by IEEE-754 rounding.
• Symbol assumptions (src/assumptions.ts) — analyzeSymbolAssumptions computes closure (e.g. prime ⇒ integer, positive, real) and conflict detection (positive vs negative), so a rewrite like sqrt(x^2) = x is only applied when sound.
• Rewrite machinery (src/pattern.ts, src/rewrite-rule.ts) — pattern matching plus RewriteRules tagged with provenance (axiom, theorem, definition, heuristic).
• Provenance (src/derivation.ts, src/proven-result.ts) — ProvenResult<T> wraps a value with a derivationChain, the assumptions used, a confidenceLevel (proven / conjectured / numerical / verified-by-independent-cas), and a verificationStatus. Invariants in createProvenResult prevent a numerical result from being dressed up as a formal proof (lean4-verified requires confidenceLevel === 'proven').
• Serialization — native JSON plus OpenMath, Content MathML, SMT-LIB, TPTP, and SCSCP encodings, so an expression can be handed to an SMT solver, a first-order ATP, or an external CAS.
• Supporting structure — an e-graph (src/egraph.ts), structural hash-consing (src/hash-consing.ts), a canonical term ordering, a numeric compiler, and an in-process ComputationResultEventBus.

@kalika/utils (libs/kalika/utils/) is the small units layer — physical dimensions, quantities, and codified physical constants — that backs the "every numerical result carries units" requirement.

A crucial honesty correction: @kalika/core is not a universal dependency. Only 13 of the 93 libraries declare a dependency on it (autodiff, classical-mechanics, electrodynamics, electronic-structure, fluid-dynamics, formal-verification, knowledge-graph, numerical, research-agents, sdk, training-data, typesetting, and core itself). The remaining ~80 mathematics/physics packages are self-contained — they do not share the Expr AST. (Earlier documentation claiming "every other library depends on @kalika/core" overstated the coupling.)

The Rust kernels (built, benchmarked, unbridged)#

@kalika/cas-engine#

A Cargo workspace at libs/kalika/cas-engine/ with three crates:

• kalika-cas-core — the kernel. Its src/lib.rs re-exports hundreds of functions across modules: integer/rational/modular/padic/ algebraic/ball (exact and certified-interval arithmetic), polynomial/sparse_polynomial (dense factorization, Gröbner bases via Buchberger/F4/F5, ideal operations, primary decomposition), and calculus (Risch transcendental/algebraic integration, Rubi, Gruntz limits, Gosper/Zeilberger/creative-telescoping summation, ODE/PDE classification). It carries Criterion benches that compare against FLINT, Singular, and Mathematica baselines, plus regression suites for limits, integration, and Risch decidability.
• kalika-cas-native — a real napi-rs Node binding (crates/kalika-cas-native/src/lib.rs) exposing KalikaCasNativeKernel with JSON-bridge methods (simplifyExpressionJson, differentiateExpressionJson, the Risch/Rubi integration bridges, zeilbergerSumExpressionJson, …), worker-thread dispatch, and zero-copy buffer helpers. It advertises NAPI version 8.
• kalika-cas-wasm — a wasm-bindgen build exposing KalikaCasWasmKernel for browser/SDK use.

The bridge crates exist and compile; what is missing is a TypeScript consumer that calls them. That integration is the natural next step, not a rewrite.

@kalika/numerical-engine#

A Cargo workspace (kalika-numerical-engine-core) whose single src/lib.rs is ~27,000 lines of real numerical linear algebra: DoubleDouble extended precision, dense Matrix<T> with LU / QR / Cholesky / Hessenberg / Schur / symmetric-eigen / SVD, Krylov solvers, sparse formats (COO, CSR, CSC, ELL, BSR, Skyline), sparse direct and iterative factorizations, preconditioners, sparse eigensolvers (Lanczos/Arnoldi), and nonlinear solvers. This is substantial, working code — earlier docs describing it as "largely planned" were wrong. As with the CAS kernel, it currently has no bridge crate and no TypeScript consumer in the live path; the compute service does its matrix math in TypeScript instead.

The live service plane#

Six applications under apps/kalika/ form the running platform. The three back-end services and the BFF are Fastify apps; all routes use a { ok, result | error } envelope under /api/v1.

BFF (apps/kalika/bff)#

The only service the browser talks to. createKalikaAuthHook (src/auth.ts) requires a bearer token on every route except /health, /ready, and the WebSocket routes; it accepts dev.<base64url> tokens (non-production only) and HS256 JWTs verified by @oshun/auth. It fans requests to the downstream services through HTTP JSON clients (src/clients.ts, default ports 3331/3332/3333) and fans realtime events back over a per-user WebSocket hub (src/realtime.ts, KalikaRealtimeHub). Upstream 5xx surface as KALIKA_UPSTREAM_ERROR (502). Sessions and preferences live in an InMemoryKalikaSessionStore.

Compute service (apps/kalika/svc-compute)#

Handles synchronous symbolic / evaluate / matrix / tensor operations and longer queued work. The engine (src/engine.ts) is the heart of the honest story: symbolic operations are implemented with string/regex manipulation — differentiateExpression pattern-matches power rules and a small table of sin/cos/exp/log; simplifyExpression strips +0/*1; solveLinearEquation only handles non-degenerate linear equations; series hard-codes the exp/sin/cos Taylor series. Symbolic results are tagged verificationStatus: 'conjectured' accordingly. By contrast the numeric paths are real: evaluate runs a genuine recursive-descent expression parser (NumericParser), and matrix determinant/inverse use real Gaussian elimination with partial pivoting (tagged 'numerical'). tensor einsum delegates to @kalika/tensor-networks.

The queue (src/queue.ts) is BullMQ-backed — in-memory by default, Redis when KALIKA_COMPUTE_QUEUE_BACKEND=redis. A QueuedComputeTask is a union over compute (a ComputeJob), ibp_reduction (Feynman integration-by-parts), or lattice_monte_carlo (a 2-D Ising sweep), with priorities interactive/batch/background and content-hashed cacheKey dedupe. A streaming WebSocket (src/streaming.ts) runs groebner_basis, large_simplification, and numerical_simulation with progress and cancel.

Notebook service (apps/kalika/svc-notebooks)#

Hosts the reactive notebook model from @kalika/notebooks. A NotebookDocument is an ordered list of typed cells; editing a cell resets its execution to idle and clears outputs (normalizeNotebookDocument invariants in model.ts). The reactive engine (libs/kalika/notebooks/src/reactive-engine.ts) analyzes which cells define and read which variables, builds a dependency graph, and plans a topological execution order distinct from document order — so changing one cell re-evaluates only its downstream dependents. Notably, the notebook CAS binding (src/cas-kernel.ts) is built around an injectable CasEngineAdapter interface over @kalika/core Expr values, not a hard-wired Rust kernel — the natural seam where the Rust CAS could later be plugged in. The service also implements export to 7 formats, multi-user collaboration (edits, CRDT updates, presence, locks), and filesystem file-sync over SSE.

Agent service (apps/kalika/svc-agents)#

Hosts a ResearchAgentLifecycleService over @kalika/research-agents, which decomposes a ResearchGoalSpecification into a typed plan of steps (scope, compute, literature, verify, reflect, synthesize, custom) and executes them with reflection between iterations. It bundles a proof agent (trying decision procedures → SMT → ATP → Lean), conjecture formulation with four-axis ranking, a multi-agent orchestrator, and literature clients (arXiv, INSPIRE-HEP, OpenAlex, Semantic Scholar, OEIS). Generic agent machinery is consumed from Nous via src/nous-integration.ts; Kalika keeps the scientific semantics.

SDK and CLI#

@kalika/sdk (libs/kalika/sdk/) is the embeddable client. Honesty note: createKalikaSdk builds a KalikaLocalCasEngine over a WasmArithmeticKernel whose WASM module (src/wasm-kernel.ts) is an 86-byte hand-assembled module exporting only f64 add/sub/mul/div — it is not the Rust CAS compiled to WASM. The SDK's symbolic operations delegate to the same string-based engine.ts as the compute service. The kalika CLI (apps/kalika/cli) runs over this SDK. The React web workbench (apps/kalika/web) provides reactive notebooks, math input, a spatial canvas, a knowledge-graph browser, and a 3-D explorer, with an extensive Playwright accessibility suite.

Data and control flow#

The dotted arrows from the Rust kernels mark the seams that are designed but not yet connected: the CasEngineAdapter interface and the compute engine are where the native CAS and numerical kernels would attach.

The domain library archipelago#

Beyond the spine, libs/kalika/ carries ~80 mathematics, physics, and materials packages. These are real, substantive TypeScript libraries — e.g. general-relativity ships curvature-tensors.ts, geodesic-solver.ts, bssn-formalism.ts, post-minkowskian-scattering.ts; quantum-mechanics ships ~14k lines across spherical harmonics, spin algebra, state representations, and scattering; tensor-networks ships MPS/MERA/DMRG; formal-verification ships Lean/Coq/Isabelle/Metamath parsers, decision procedures, a first-order ATP, and cross-CAS verification. They are mostly self-contained: each implements its own internal types and numerical algorithms rather than building on the shared Expr AST or calling the Rust kernels. Treat each as an independent computational library that happens to live under the Kalika umbrella, grouped thematically:

• Pure mathematics — algebra, algebraic-geometry, analysis, number-theory, topology, three-manifolds, category-theory, higher-categories, combinatorics, algebraic-combinatorics, probability, measure-theory, optimization, approximation, differential-geometry, geometric-analysis, symplectic, noncommutative-geometry, vertex-algebras, quantum-groups, cohomology.
• Theoretical physics — quantum-mechanics, quantum-field-theory, general-relativity, statistical-mechanics, lie-theory, string-theory, condensed-matter, cosmology, hep-phenomenology, quantum-gravity, gravitational-waves, lattice, information-theory, and capstones (non-perturbative, supersymmetry, integrable-systems, spectral-geometry, open-quantum-systems, quantum-chaos, topological-qc, neutrino-physics, bbn, entanglement).
• Classical/continuum physics — classical-mechanics, electrodynamics, fluid-dynamics, thermodynamics, optics, plasma-physics, astrophysics, nonlinear-dynamics, atomic-physics, mathematical-physics.
• Computational engine — numerical, autodiff / autodiff-core, hpc-orchestrator, sdp-core, surrogate, tensor-networks, tensor.
• Verification / AI research / frontier methods — formal-verification, symbolic-regression, neural-physics, tropical, positive-geometry, periods, resurgence, bootstrap, matrix-models.
• Research platform — notebooks, renderer, typesetting, knowledge-graph, citations, database, jupyter-kernel, training-data.

Materials science (partial)#

electronic-structure is the materials package with the most code, but it is partially built, not complete. It implements real structural I/O (CIF, POSCAR, Quantum ESPRESSO, ABINIT, XYZ, Materials Project), pseudopotential handling (cutoff convergence, delta-factor, spin-orbit), k-point grids/paths, lattice classification, and a kernel-loader.ts that selects a native-vs-WASM runtime descriptor. But the actual solver directories — scf/, plane-wave/, band-structure/, charge-analysis/, optimization/, parallel/ — are empty .gitkeep placeholders. So the Kohn-Sham DFT scaffolding and data model exist; the SCF compute kernel does not yet. xc-functionals and wannier accompany it. The broader materials program (crystallography, many-body methods, lattice dynamics, MD, ML potentials, spectroscopy, thermodynamics, functional materials, code interoperability, multiscale engineering) and the autonomous-experimentation loop are roadmap-only (TODO Phases 116-131).

A few packages are effectively label-only: arithmetic and calculus mainly export a backend-name constant (KALIKA_CALCULUS_BACKEND = '@kalika/cas-engine') pointing at where compute will route once the Rust kernel is bridged.

Invariants, failure modes, and extension points#

Invariants. Provenance integrity is enforced in code, not by convention: createProvenResult rejects formal verification statuses without a proven confidence level, so a heuristic can never masquerade as a theorem. Notebook outputs enforce a MIME contract (normalizeOutput — a data-table row width must equal its column count); an errored cell execution must carry an error payload. The reactive engine guarantees the visible document reflects the latest inputs via topological re-evaluation. Queued tasks dedupe on a content-hashed cacheKey, the operational basis of reproducible compute.

Failure modes a maintainer must know. (1) The string-based symbolic engine is intentionally narrow: anything outside its pattern tables returns an unevaluated Derivative(...)/Integral(...)/Limit(...) form rather than a real answer — do not mistake its 'conjectured' results for kernel-grade output. (2) Persistence is in-memory by default across the BFF session store, the notebook repository (hydrated on startup), and the agent store; a durable Postgres/object store is planned, so process restarts lose state unless Redis is configured for the queue. (3) The Rust kernels are unbridged — a change there has no effect on the running services until the bridge work is done. (4) Eventing is in-process / WebSocket / SSE only; the cross-domain event bus (ExpressionEvaluated, ProofAttemptCompleted, …) is planned.

Extension points. New symbolic rewrites are added as provenance-tagged RewriteRules in @kalika/core. New compute operations require extending the relevant closed enum (SymbolicOperation, MatrixOperation, TensorOperation, QueuedComputeTask['kind']) and its handler. New research behaviors plug into ResearchPlanStepKind / MultiAgentSpecialistKind. The notebook CasEngineAdapter and the electronic-structure selectKernelRuntime descriptor are the deliberate seams for swapping in the native/WASM kernels.

Cross-domain boundaries#

Kalika owns scientific kernels and workflows; it deliberately does not own the product concerns of its consumers.

• Sophia owns general knowledge management and RAG; Kalika owns its own scientific knowledge graph (@kalika/knowledge-graph) of mathematical objects, proofs, methods, and constants.
• Nous owns generic AI-model infrastructure and the agentic-scientist substrate; Kalika consumes it through research-agents/src/nous-integration.ts while keeping the meaning of a conjecture, proof, or campaign in Kalika.
• Nyx owns real observatory/sky-survey calculations; Kalika keeps theoretical astrophysics and mathematical physics. The boundary is the telescope.
• Iris supplies the conversational/assistant interfaces the workbench consumes.
• Saraswati, Brigid, Cybele, Airmid, Demeter, Maat consume validated Kalika outputs (technology, industrial, built-environment, botanical, agriculture, planning) without owning the kernels — so kernel improvements benefit every consumer at once.

Honest status summary#

Implemented and shipping: @kalika/core (AST + provenance + serialization), the reactive notebook model and service, the BFF (auth, fan-out, realtime hub), the compute service's queue and its real numeric paths, the agent substrate and literature clients, @kalika/formal-verification, and the broad set of self-contained mathematics/physics libraries.

Built but not yet integrated: the Rust kalika-cas-core and kalika-numerical-engine-core kernels and their napi/wasm bridges (depended on by 0 and 1 TS package respectively). The live symbolic path is the lighter string-based TypeScript engine.

Partial: electronic-structure (real I/O, pseudopotentials, types, runtime selection; empty SCF/plane-wave/band-structure solver directories).

Planned/roadmap: durable Postgres + object persistence, the cross-domain event bus, the full materials-science program, and the autonomous-experimentation loop (TODO Phases 116-131). The architecture's clearest near-term work is closing the seam between the two compute substrates — wiring the Rust kernels into the CasEngineAdapter and the compute engine.