expand_less **Hyperon Experimental**{{Home|view:link;title:Home}} / {{MeTTa Programming Language|view:link;title:MeTTa Programming Language}} / {{MeTTa Programming Language+Hyperon Experimental|view:link;title:Hyperon Experimental}} / Hyperon Experimental Full

Hyperon Experimental is the official trueagi-io Rust reference implementation of the MeTTa runtime. At HEAD `3f76dc46`3f76dc46 (v0.2.10, 2026-02-11), it is the foundational MeTTa runtime substrate that all alternative MeTTa runtimes either port, transpile, embed, or bridge.

## Source Identity

-

Origin: [https://github.com/trueagi-io/hyperon-experimental](https://github.com/trueagi-io/hyperon-experimental)https://github.com/trueagi-io/hyperon-experimental
- HEAD pinned: `3f76dc460da6961f57f69f6c3e550c59c74ada83`3f76dc460da6961f57f69f6c3e550c59c74ada83
- Tagged release: v0.2.10 (Merge PR #1075, 2026-02-11, Vitaly Bogdanov)
- Tag timeline: v0.2.1 (2024-10-23) to v0.2.10 (2026-02-11), 10 minor releases over ~16 months
- 7-crate Rust workspace: `hyperon-common`,hyperon-common, `hyperon-atom`,hyperon-atom, `hyperon-space`,hyperon-space, `hyperon-macros`,hyperon-macros, `lib`,lib, `c`,c, `repl`repl
- Non-workspace dirs: `python/`python/ (pybind11 bindings + sandbox), `integration_tests/das/`,integration_tests/das/, `docs/`docs/
- Tracked-file inventory: 296 files (85 .rs + 67 .metta + 65 .py + 22 .md + smaller)
- Primary maintainer: Vitaly Bogdanov (2,137 commits all-time)


## Architecture

### Interpreter Semantics

`[SMALL-STEP-INTERPRETER]`
[SMALL-STEP-INTERPRETER] `[NONDETERMINISTIC-BRANCHING]`

[NONDETERMINISTIC-BRANCHING]
Stack-based, plan/state-driven, nondeterministic. **NOT**NOT a deterministic "first match wins" rewrite engine — multiple matches produce multiple results. Key entry points in `lib/src/metta/interpreter.rs`:

-lib/src/metta/interpreter.rs:

interpret_step `interpret_step` (L269) — main reduction step
-interpret_stack `interpret_stack` (L374) — stack dispatch with depth enforcement (L392)
-eval_impl `eval_impl` (L504), `eval_result`eval_result (L559), `query`query (L604)
-chain `chain` (L687), `collapse-bind`collapse-bind (L746), `unify`unify (L809), `superpose-bind`superpose-bind (L893)
- Native grounded-symbol calls (L922)

**Boundary**:

Boundary: programs requiring deterministic dispatch must use mutually exclusive patterns. Catchall equations (`$_`,($_, `$other`)$other) alongside specific equations produce multiple reductions — this is documented language semantics, not a defect.

### Type System

`[DYNAMIC-CHECKED]`

`lib/src/metta/types.rs`:

-
[DYNAMIC-CHECKED]
lib/src/metta/types.rs:

%Undefined% `%Undefined%` is permissive wildcard — assigned to atoms without a user type, matches any required type (L18-19)
-check_arg_types `check_arg_types` (L65), `get_atom_types`get_atom_types (L327), `get_application_types`get_application_types (L512), `UndefinedTypeMatch`UndefinedTypeMatch (L526)
-check_type `check_type` (L602), `validate_atom`validate_atom (L637)
- Dependent-type tests at L817, L861, L1120, L1139
- Open TODOs at L42, L379, L397, L494-499, L1177, L1225, L1298



Hyperon Experimental supports expressive type checking, but should **NOT**NOT be described as a fully-settled categorical/dependent-type verifier.

### Standard Library

`[HYBRID-RUST-PLUS-METTA-STDLIB]`


[HYBRID-RUST-PLUS-METTA-STDLIB]
Split between Rust-side token registrations under `lib/src/metta/runner/stdlib/`lib/src/metta/runner/stdlib/ and MeTTa-side definitions in `stdlib.metta`stdlib.metta (1,421 lines). Cross-runtime audits **must**must cover both layers.


Rust-side modules:

-

arithmetics.rs `arithmetics.rs` (L162-198): `+`,+, `-`,-, `*`,*, `/`,/, `%`,%, ``,<, `=`,>, `and`,<=, `or`,>=, `not`,and, `xor`,or, not, xor, division
-atom.rs `atom.rs` (L449-474): `unique-atom`,unique-atom, `union-atom`,union-atom, `intersection-atom`,intersection-atom, `max-atom`,max-atom, `min-atom`,min-atom, `size-atom`,size-atom, `index-atom`,index-atom, `subtraction-atom`,subtraction-atom, `get-type`,get-type, `get-metatype`,get-metatype, `get-type-space`get-type-space
-core.rs `core.rs` (L336-362): `pragma!`,pragma!, `nop`,nop, `sealed`,sealed, `==`,==, `match`,match, `if-equal`,if-equal, `superpose`,superpose, `capture`,capture, `_minimal-foldl-atom`_minimal-foldl-atom
-debug.rs `debug.rs` (L155-177): `trace!`,trace!, `print-alternatives!`,print-alternatives!, `=alpha`=alpha
-math.rs `math.rs` (L408-443): `pow-math`,pow-math, `sqrt-math`,sqrt-math, `abs-math`,abs-math, `log-math`,log-math, etc., plus `PI`PI and `EXP`EXP constants
-module.rs `module.rs` (L280-298): `import!`import! (L290), `include`,include, `mod-space!`,mod-space!, `print-mods!`,print-mods!, `bind!`bind! (L269), `module-space-no-deps`module-space-no-deps
-package.rs `package.rs` (L113-117): `register-module!`,register-module!, `git-module!`git-module!
-space.rs `space.rs` (L206-223): `new-space`,new-space, `get-state`,get-state, `change-state!`,change-state!, `get-atoms`,get-atoms, `add-atom`,add-atom, `remove-atom`

remove-atom

MeTTa-side definitions in `stdlib.metta`:stdlib.metta: `return`return (L47), `function`function (L54), `eval`eval (L61), `chain`chain (L78), `unify`unify (L88), `cons-atom`cons-atom (L96), `decons-atom`decons-atom (L103), `collapse-bind`collapse-bind (L239), `superpose-bind`superpose-bind (L246), `metta`metta (L255), `switch`switch (L345-362), `if`if (L511-513), `let`/`let*`let/let* (L542-553), `collapse`collapse (L1203), `case`case (L1224-1233).

**NOTE**:
NOTE: there is **NO**NO `replace-atom!`replace-atom! MeTTa op at HEAD. PATCH-2 from the AtomSpace Integration Phase 4 cluster pilot recommends adding it.

### Built-in Modules

`[BUILTIN-FULLY-WIRED]`

`lib/src/metta/runner/builtin_mods/mod.rs`
[BUILTIN-FULLY-WIRED]
lib/src/metta/runner/builtin_mods/mod.rs registers six loaders:

-

random, `random`,skel, `skel`,fileio, `fileio`,json `json`
-catalog `catalog`(pkg_mgmt (`pkg_mgmt` Cargo feature)
-das `das`(das (`das` Cargo feature, default-enabled per `lib/Cargo.toml:46`)

lib/Cargo.toml:46)

Each module pairs a `.rs`.rs registration file with a `.metta`.metta doc file (`catalog.metta`,(catalog.metta, `das.metta`,das.metta, `fileio.metta`,fileio.metta, `json.metta`,json.metta, `random.metta`,random.metta, `skel.metta`).

skel.metta).
DAS is available as a default feature and builtin module surface, but does **NOT**NOT mean a running distributed DAS service is embedded in the local runtime — `metta-bus-client`metta-bus-client connects to a remote DAS service.

### Module System

`[MODULE-SYSTEM-PARTIAL]`


[MODULE-SYSTEM-PARTIAL]
Implemented and active but evolving (per `docs/modules_internal_discussion.md`'sdocs/modules_internal_discussion.md's "poor man's" public/private scope concept).

`lib/src/metta/runner/modules/mod.rs`:

-
lib/src/metta/runner/modules/mod.rs:

ModId `ModId` (L27), `MettaMod`MettaMod (L56), resource and loader fields (L58, L62)
-import_dependency_as `import_dependency_as` (L107), `import_item_from_dependency_as`import_item_from_dependency_as (L131), `import_all_from_dependency`import_all_from_dependency (L181)
- Accessors path/name/package/space/tokenizer/resource (L251-278)
- Descriptor state (L314), module init (L439), `ModuleLoader`ModuleLoader trait (L563), `Resource`Resource (L608)
- Name resolution at `mod_names.rs:265`mod_names.rs:265 and `:276`

:276

Imports via `import!`import! (registered at `stdlib/module.rs:290`)stdlib/module.rs:290) create separate `DynSpace`DynSpace instances.

### AtomIndex / AtomTrie

`[IN-MEMORY-ATOMTRIE-INDEX]`
[IN-MEMORY-ATOMTRIE-INDEX] `[NO-BENCHMARK-CLAIMS]`

`hyperon-space/src/index/`:

-[NO-BENCHMARK-CLAIMS]
hyperon-space/src/index/:

AtomIndex `AtomIndex`(mod.rs:159), (`mod.rs:159`), insert (`:177`),(:177), query (`:192`),(:192), remove (`:207`)(:207)
-AtomTrie `AtomTrie`(trie.rs:201, (`trie.rs:201`, 930 lines), insert (`:232`),(:232), query (`:261`),(:261), remove (`:395`)

(:395)

Concentrated implementation period 2025-01-31 to 2025-02-11 (initial implementation, GroundingSpace integration, duplication strategy parameter, AtomStorage/AtomTrieNode separation, compactness improvements). Size-prefix optimization landed at `120c2279`120c2279 (2025-08-26) — *"Prefix"Prefix expressions with size in atomspace index to recognize them faster"*.

**NO**faster".
NO quantitative scaling ceilings claimed at this time. Existing benches at `hyperon-space/benches/atom_index.rs`hyperon-space/benches/atom_index.rs and `lib/benches/grounding_space.rs`lib/benches/grounding_space.rs operate at 100/x10/x100 atom scales only. An empirical bench harness is required for any production scaling claims.

### Hyperon Space Write API and Observer Pattern


(Phase 4 prior art — re-confirmed at HEAD)


The Hyperon Space write surface is complete at the Space/C/Python layers:

-

SpaceMut::add `SpaceMut::add` / `remove`remove / `replace`replace at `hyperon-space/src/lib.rs:237/255/275`hyperon-space/src/lib.rs:237/255/275
-GroundingSpace[D] `GroundingSpace[D]` (generic over duplication strategy `D`)D) concrete impl at `lib/src/space/grounding/mod.rs:14-21`;lib/src/space/grounding/mod.rs:14-21; inherent `add`/`remove`/`replace`add/remove/replace at `:70/:92/:119`:70/:92/:119
- C-API write surface at `c/src/space.rs:140-143`;c/src/space.rs:140-143; observer registration at `c/src/space.rs:464`c/src/space.rs:464
- Python write surface at `python/hyperon/base.py:205-221`python/hyperon/base.py:205-221
-SpaceObserver `SpaceObserver` / `SpaceEvent`SpaceEvent / `SpaceCommon`SpaceCommon observer pattern at `hyperon-space/src/lib.rs:22-126`hyperon-space/src/lib.rs:22-126
- Single-process / single-threaded by intentional design (per maintainer comment at `c/src/space.rs:117-119`)

**PATCH-1**c/src/space.rs:117-119)

PATCH-1 (REQUIRED for Phase 4 mirror integration): pybind11 binding for `space_register_observer`space_register_observer in `python/hyperonpy.cpp`python/hyperonpy.cpp is missing. Path II (Rust-only bridge service) is the Phase 4 implementation strategy; Path IV (PR upstream) is the upstream-contribution strategy.

### Python Bindings

`[PY-PARTIAL-WITH-GAPS]`


[PY-PARTIAL-WITH-GAPS]
Broad coverage:

-

SpaceRef `SpaceRef`(base.py:168), (`base.py:168`),add_atom/remove_atom/replace_atom `add_atom`/`remove_atom`/`replace_atom` (L205-221)
-RunnerState `RunnerState`(runner.py:24), (`runner.py:24`), MeTTa class (L107), run (L206), evaluate atom (L216)
-hyperonpy.cpp:1017-1026 `hyperonpy.cpp:1017-1026` interpreter stepping
-hyperonpy.cpp:1047-1053 `hyperonpy.cpp:1047-1053` type checking and lookup
-hyperonpy.cpp:1070-1122 `hyperonpy.cpp:1070-1122` run context, MeTTa construction, module loading

**Gap**:

Gap: Python observer registration is **NOT**NOT bound (PATCH-1 above).


EventAgent (PR #852, merged commit `2fd826d4`2fd826d4 2025-03-14) ships at HEAD: `python/hyperon/exts/agents/agent_base.py:202-293`python/hyperon/exts/agents/agent_base.py:202-293 defines `EventAgent`,EventAgent, `BasicEventBus`BasicEventBus at `events/basic_bus.py:6`.events/basic_bus.py:6. EventAgent uses a generic event bus, **NOT**NOT bound to `SpaceEvent`/`SpaceObserver`SpaceEvent/SpaceObserver — they are disjoint event paths in the same repo.

### C Bindings

`[C-CORE-ONLY]`


[C-CORE-ONLY]
Broad runtime surface in `c/src/`:

-c/src/:

space.rs:69 `space.rs:69`space_new; `space_new`;:140-170 `:140-170` add/remove/replace; `:184-237`:184-237 query/subst/count/iter; `:401-419`:401-419 event accessors; `:464`:464 `space_register_observer`;space_register_observer; `:632-673`:632-673 event constructors
-metta.rs:838-882 `metta.rs:838-882` MeTTa instance construction; `:957-969`:957-969 space/tokenizer accessors; `:1005`:1005 parser-input run; `:1035`:1035 atom evaluation; `:1062-1094`:1062-1094 module loading; `:1305-1407`:1305-1407 runner-state stepping



C headers are **auto-generated**auto-generated by cbindgen (per `c/cbindgen.toml`);c/cbindgen.toml); there is **NO**NO source-controlled `c/include/`c/include/ directory.

### Sandbox Modules

`python/sandbox/`
python/sandbox/ is a prototype zone, **NOT**NOT part of the packaged Python module (`python/pyproject.toml:38`(python/pyproject.toml:38 packages only `hyperon`).

| hyperon).


Module | Verdict | Notes |
|---|---|---|
| `sql_space`
sql_space[SANDBOX-PROTOTYPE] | `[SANDBOX-PROTOTYPE]` | Postgres custom-Space; 130 lines; naive SQL string concat; not production |
| mork[SANDBOX-PROTOTYPE]`mork` | `[SANDBOX-PROTOTYPE]` | TODOs at L32, L47 |
| neurospace[SANDBOX-PROTOTYPE]`neurospace` | `[SANDBOX-PROTOTYPE]` | NeuralSpace, IntentSpace |
| jetta[SANDBOX-EXAMPLE-ONLY]`jetta` | `[SANDBOX-EXAMPLE-ONLY]` | Requires cloning `trueagi-io/jetta`trueagi-io/jetta |
|numpy[SANDBOX-PROTOTYPE]numme.py `numpy` | `[SANDBOX-PROTOTYPE]` | `numme.py` experimental |
|pytorch[SANDBOX-PROTOTYPE]torchme.py `pytorch` | `[SANDBOX-PROTOTYPE]` | `torchme.py` Func-Signature JSON for type-aware tensor ops |
|bhv_binding `bhv_binding` | unclassified | Source 1 did not enumerate |
|repl `repl` | unclassified | Relationship to top-level `repl/`repl/ Rust crate not characterized |
|resolve `resolve` | unclassified | Source 1 did not enumerate |




S2-S6 must treat these as precedent and adjacency, **NOT**NOT as packaged interfaces.

### Test Coverage

`[TEST-COVERAGE-ADEQUATE]`


[TEST-COVERAGE-ADEQUATE]
Multilayer:

-

Rust library tests in `lib/tests/`lib/tests/ + inline `#[test]`#[test] blocks (52 in `interpreter.rs`,interpreter.rs, 38 in `types.rs`)types.rs)
- C tests in `c/tests/`:c/tests/: `check_atom.c`,check_atom.c, `check_runner.c`,check_runner.c, `check_space.c`,check_space.c, `check_types.c`check_types.c
- Python tests in `python/tests/`python/tests/
- DAS integration tests in `integration_tests/das/`integration_tests/das/
- Test-corpus path-count: 101 files



Static audit only — tests not run during cluster-pilot extraction.

## v0.2.x Runtime Quirks Re-Verified at v0.2.10


The Magi project memory `reference_hyperon_0210_quirks.md`reference_hyperon_0210_quirks.md was originally pinned to v0.2.1 (MAGUS pin). Re-verified at HEAD `3f76dc46`3f76dc46 (v0.2.10):

-

Q-1 **Q-1 — bind! + new-space**:new-space: `[QUIRK-CONFIRMED-AT-HEAD]`.[QUIRK-CONFIRMED-AT-HEAD]. `BindOp::execute`BindOp::execute (`stdlib/module.rs:269+`)(stdlib/module.rs:269+) registers a token in the tokenizer. NO code path clears or garbage-collects atoms in an already-bound space. Operational guidance: do NOT treat `!(bind!!(bind! &name&name (new-space))`(new-space)) as a reset of an existing live space. Use explicit `(match(match &name&name (pattern) (remove-atom &name&name (pattern)))`(pattern))) workaround.
-Q-2 **Q-2 — cond**:cond: `[QUIRK-FIXED-SINCE-V0-2-1]`[QUIRK-FIXED-SINCE-V0-2-1] (via absence). `cond`cond is **NOT**NOT a builtin operator at HEAD. Use `if`,if, `case`,case, `match`,match, or user-defined equations. The original v0.2.1 quirk "cond is non-reducing" is no longer applicable because `cond`cond is not implemented.
-Q-3 **Q-3 — catchall multi-reduction**:multi-reduction: `[QUIRK-CONFIRMED-AT-HEAD]`.[QUIRK-CONFIRMED-AT-HEAD]. This is documented nondeterministic semantics, not a defect. Programs requiring deterministic dispatch must use mutually exclusive patterns; e.g., enumerate all symbols explicitly instead of using a generic variable fallback.


## Cluster-Pilot Provenance


Source 1 of the MeTTa runtime cluster pilot (closed 2026-05-08). Three-way reviewer reconciliation at:

- `scripts/archive/metta_runtime_pilot/source1_hyperon_experimental/findings_reconciled_crossmodel.txt`



scripts/archive/metta_runtime_pilot/source1_hyperon_experimental/findings_reconciled_crossmodel.txt

Phase 4 prior art locked from AtomSpace Integration Phase 4 cluster pilot (closed 2026-05-05): Source 2 reconciliation at `scripts/archive/atomspace_integration_phase4/source2_hyperon_space_writeapi/findings_reconciled_crossmodel.txt`.scripts/archive/atomspace_integration_phase4/source2_hyperon_space_writeapi/findings_reconciled_crossmodel.txt.

## Cross-Source Forwards (S2 to S6)


For PeTTa+metta-morph (S2), MeTTaTron (S3), MeTTaIL+FormalMeTTa (S4), MeTTaLog (S5), jetta+atomspace-metta (S6):

-

Stdlib parity audits cover **both**both Rust-token-registration AND MeTTa-side `stdlib.metta`stdlib.metta definitions
- Compare against nondeterministic small-step interpreter, **NOT**NOT deterministic rewrite assumption
- Type-system claims compared against dynamic `%Undefined%`%Undefined% wildcard baseline
- Module-system comparison is a major axis (active but evolving target)
- 0.2.x quirk verification baseline at HEAD `3f76dc46`3f76dc46