Completes support for PathMap pattern matching and integrates support for MeTTaTron

[dylon]

The main changes include:

• Completes PathMap decomposition support for pattern matching in Rholang
• Integrates MeTTaTron into Rholang

The original PathMap integration was added as part of the initial MeTTaTron demo and its development was deprioritized shortly before pattern matching support was completed. This completes it as part of the MeTTaTron integration.

The sequence of evaluating a MeTTaTron application in parts follows:

1. Instantiate an instance of the compiler with new mettaCompile(`rho:metta:compile`) { ... }
2. Within the new block, compile a snippet of MeTTa text via: for (@compiledState <- mettaCompile!?(code)) { ... }. This will return an instance of a MeTTaTron state whose inputs have been populated with the parsed atoms from the code snippet (s-expressions).
3. Within the for block, begin evaluation of the MeTTaTron app against an empty PathMap context, e.g. {||}.run(compiledState) (where {||} denotes the empty PathMap). This will evaluate the atoms in compiledState within the empty context (no pre-existing atoms in its atom space). Most likely, the MeTTa snippet being evaluated will insert atoms into the atom space. The return value will be a new MeTTaTron state representing the updated context after evaluation, which is to say, it contains the side-effects to the atom space of the evaluated expressions and all the outputs from evaluation.
4. Most likely, you will want to persist the updated state for additional refinement, so you can write it to a channel like so: persistentState!({||}.run(compiledState)).
5. When you are ready to run your next snippet, read the current state off persistentState via: for (@state <- persistentState) { ... } and use state in place of the empty PathMap {||} from step 3. Repeat the steps as needed.

For a complete example how this works, take a look at the robot_planning.rho example from MeTTaTron.

The communication mechanism will be greatly simplified and made much more efficient once we have a Reified RSpace for MeTTaTron, but that has not been designed yet.

The MeTTaTron integration is feature-gated behind "mettatron" in case others wish to build Rholang without it.

[AndriiS-DevBrother]

Suggested Improvements

1. Restore -D warnings in CI

It looks like -D warnings was dropped from RUSTFLAGS — would it be possible to restore it? If MeTTaTron emits warnings that block the build, perhaps targeted #[allow(...)] or -A specific_lint could work instead of removing it entirely?

2. External dependencies on personal forks

CI and [patch] sections currently point to github.com/dylon/PathMap and github.com/dylon/MORK. Are there plans to migrate these under the F1R3FLY-io org or publish to crates.io? That would help avoid any risk if the personal repos change.

3. Deduplicate spatial matcher logic

The three EPathmapBody / GByteArray(MTTS) / GByteArray(MTTL) match arms in spatial_matcher.rs share ~40 lines of identical sort/dedup/remainder/merger code. Would it make sense to extract a shared helper to reduce duplication?

4. block_in_place runtime assumption

The run method uses block_in_place + Handle::current().block_on(), which requires a multi-threaded Tokio runtime. The CLI switch to new_multi_thread() covers that path — could we also verify FFI callers are safe, or add a guard with a friendlier error message?

5. Error-as-value pattern in run

Deserialization/evaluation failures return Ok(metta_run_error_expr(...)) instead of Err(...). Would it be helpful to add a doc comment explaining this contract so callers know they need to pattern-match for errors?

6. Pin Docker dependency clones

The Dockerfile uses git clone --branch <branch> — would pinning to specific commit SHAs be feasible for more reproducible builds?

7. Document ../PathMap build prerequisite

The [patch.crates-io] with path = "../PathMap" means the workspace won't build without a sibling clone. It might help new contributors to mention this in the README or a CONTRIBUTING guide.

8. Incorrect Rholang syntax in metta_compile doc comment

The doc examples use @"rho:metta:compile" which is not valid Rholang syntax. System URN channels must be bound via new, e.g. new mettaCompile(\rho:metta:compile`) in { ... }, consistent with how stdout(`rho:io:stdout`)` works.

9. Missing Rholang example for MeTTa/PathMap

Other system processes like stdout, gpt4, ollama, etc. have corresponding example .rho files in rholang/examples/. Would it be worth adding a rholang/examples/metta_compile.rho (and maybe a pathmap.rho) to demonstrate the new functionality?

10. Undocumented binary format parsing in pretty_printer.rs

~230 lines of new code in pretty_printer.rs manually parse custom binary formats (MTTS, MTTL) using raw byte offsets and magic numbers. The functions is_metta_space_bytes and is_metta_large_exprs_bytes are marked #[allow(dead_code)] (appear unused in this file). The binary wire format (magic bytes, field sizes, offsets) has no specification reference. Could we get documentation on these formats and clarify whether the dead-code functions are needed?

11. Unnecessary build.sbt changes?

This PR targets rust/dev where Scala no longer invokes Rust at runtime. The build.sbt changes add run / fork, JNA library paths, and LD_PRELOAD for .so files — are these still needed? If the Scala node doesn't load Rust libraries, these changes may be dead configuration.

[AndriiS-DevBrother]

It looks like -D warnings was removed here — was this intentional to work around MeTTaTron warnings? If so, would it be possible to use targeted #[allow(...)] on specific items or -A specific_lint in RUSTFLAGS to keep the warnings-as-errors policy for the rest of the codebase?

[AndriiS-DevBrother]

[patch.crates-io] pathmap = { path = "../PathMap" } means the workspace won't build without a sibling PathMap clone. New contributors might hit a confusing build failure — would it be worth adding a note about this in the README or a setup guide?

[AndriiS-DevBrother]

The EPathmapBody ↔ EPathmapBody, GByteArray(MTTS) ↔ EPathmapBody, and GByteArray(MTTL) ↔ EPathmapBody arms share ~40 lines of identical logic (sort/dedup/remainder extraction/merger/list_match_single_). Would it make sense to extract this into a shared helper? Something like:

fn pathmap_match_inner(
    &mut self,
    mut t_elements: Vec<Par>,
    p_pathmap: &EPathMap,
) -> Option<()> {
    t_elements.sort(); t_elements.dedup();
    // ... shared remainder + merger logic
}

[AndriiS-DevBrother]

block_in_place + Handle::current().block_on() will panic on single-threaded Tokio runtimes. The rholang_cli.rs switch to new_multi_thread() covers the CLI path — could we also verify that FFI callers (e.g. create_runtime_with_test_framework) use a multi-threaded runtime? Adding a guard with a friendly error message instead of a raw panic might be worth considering.

Also: deserialization/evaluation failures in the run method return Ok(metta_run_error_expr(...)) — errors as data values rather than Err(...). This is a valid design choice, but callers need to know they must pattern-match the result Par to detect failures. Would it be helpful to add a doc comment explaining this error-as-value contract and what the error Par structure looks like?

[AndriiS-DevBrother]

Extracting source code via self.pretty_printer.build_string_from_message(source) and then stripping quotes could be fragile if source isn't a simple GString. Would it be safer to extract the string directly from the Par?

let src = match source.exprs.first().and_then(|e| e.expr_instance.as_ref()) {
    Some(ExprInstance::GString(s)) => s.clone(),
    _ => return Err(illegal_argument_error("metta_compile: expected string argument")),
};

[AndriiS-DevBrother]

Other system processes like stdout, gpt4, ollama, etc. have corresponding example .rho files in rholang/examples/. Would it be worth adding a rholang/examples/metta_compile.rho (and maybe a pathmap.rho) to demonstrate the new MeTTa and PathMap functionality? It would help users discover and test the new features.

[AndriiS-DevBrother]

git clone --branch <branch> could be affected by force-pushes — would it be feasible to pin to specific commit SHAs for more reproducible Docker builds?

RUN git clone https://github.com/dylon/PathMap.git /PathMap && \
    cd /PathMap && git checkout <sha>

[AndriiS-DevBrother]

The catch-all here treats any unrecognized symbol as GString, which could silently mask bugs if new Par types are added to the encoder but missed in the decoder. Would it make sense to log a warning for unexpected symbols, or maintain an explicit allowlist of known patterns?

[AndriiS-DevBrother]

Minor nit: parameters named _ps, _locally_free, etc. conventionally signal unused parameters in Rust. Since these are all used, dropping the underscore prefixes might be clearer.

[metaweta]

Ground strings should support escaped characters since https://github.com/F1R3FLY-io/f1r3node/pull/228/changes

[metaweta]

If you don't get back the original variable names, please add a comment to that effect to the description of the function.