# 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 `RewriteRule`s 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

```mermaid
flowchart TD
  subgraph Clients
    WEB[web workbench React]
    SDK[@kalika/sdk + kalika CLI]
    EXT[external consumer domains]
  end

  WEB -->|bearer JWT, /api/v1| BFF[BFF Fastify auth + realtime hub]
  BFF -->|HTTP JSON :3331| SVCC[svc-compute]
  BFF -->|HTTP JSON :3333| SVCN[svc-notebooks]
  BFF -->|HTTP JSON :3332| SVCA[svc-agents]
  BFF -. WebSocket events .-> WEB

  SVCC --> ENG[engine.ts string symbolic + real numeric]
  SVCC --> Q[BullMQ queue memory/redis]
  ENG --> TN[@kalika/tensor-networks einsum]

  SVCN --> RE[reactive-engine topo plan]
  RE --> CK[CasEngineAdapter over @kalika/core Expr]

  SVCA --> RA[@kalika/research-agents]
  RA --> FV[@kalika/formal-verification Lean/SMT/ATP]
  RA --> LIT[arXiv / INSPIRE / OpenAlex clients]
  RA -.->|generic agent machinery| NOUS[(Nous)]

  CORE[@kalika/core Expr + ProvenResult] --- ENG
  CORE --- CK
  CORE --- FV

  SDK --> WASM[86-byte WasmArithmeticKernel f64 only]
  SDK --> ENG2[same string engine.ts]

  subgraph RustKernels[Rust kernels — built, benchmarked, NOT bridged]
    CAS[kalika-cas-core + napi/wasm]
    NUM[kalika-numerical-engine-core 27k LOC]
  end
  CAS -. integration seam .-> CK
  NUM -. integration seam .-> ENG

  EXT -->|validated outputs| BFF
```

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
`RewriteRule`s 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.