# @nous/world-model-core

Shared foundations for the Phase 176 sovereign neural-world-model stack.

Provides the abstractions every learned simulator in Phase 176 builds on:

- **`WorldModel<S, A, O>`** — the uniform interface (`encode` / `step` /
  `imagine` / `getUncertainty`) implemented by DreamerV3's RSSM, MuZero's
  dynamics net, Genie's ST-transformer, and DIAMOND's diffusion dynamics.
- **`LatentState`** — a tagged union of `DeterministicLatent`,
  `StochasticLatent` (diagonal Gaussian), `CategoricalLatent` (k×c one-hots,
  DreamerV3), and `TokenLatent` (VQ codebook grid, Genie), with real KL /
  entropy / balancing math and flat (de)serialisation.
- **`ActionSpace`** — `ContinuousBox`, `DiscreteFinite`, `MultiDiscrete`, and
  `MultiModal` (mouse + keyboard + text), plus a `LatentActionCodebook`
  (k-means-fit VQ quantiser) for Genie-style latent action tokens.
- **`ReplayBuffer`** — a prioritised (sum-tree) replay + trajectory dataset that
  ingests Phase 85 flywheel sessions and serves n-step returns and
  variable-horizon sequence slices that respect episode boundaries.
- **`ImaginationEngine`** — the DreamerV3 λ-return / GAE rollout engine reused
  across Dreamer, MuZero, and latent policy-gradient training.

Everything is pure TypeScript with no runtime dependencies; the numeric formulas
(KL divergence, λ-returns, prioritised IS weights) are unit-tested against
closed-form values.

```
npx vitest run --root libs/nous/world-model-core
```