this-me

Rust ground for the modern .me semantic kernel.

this-me is the Rust implementation of the .me kernel: append-only semantic memory, hash-chain integrity, path selectors, operators, derivations, secret/noise scopes, key wrapping, identity proofs, snapshots, runtime events, and an embeddable host wrapper.

The crate is intentionally small at the edge:

• use [kernel::Kernel] when you want the semantic core directly;
• use [runtime::KernelRuntime] when you are embedding .me behind a host, daemon, HTTP surface, WebSocket stream, or local app;
• use [storage::JsonFileStore] when you want a file-backed owner snapshot;
• use [me_uri] when you need canonical me:// parsing and DNS projection.

Manual Rust implementation docs live at neurons-me.github.io/.me/Rust/.

Quick Start

use this_me::kernel::{Kernel, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut me = Kernel::new();

    me.postulate("wallet.income", 100_u64)?;
    me.postulate("wallet.expenses", 40_u64)?;
    me.derive("", "wallet.total", "wallet.income - wallet.expenses")?;

    assert_eq!(me.read("wallet.total"), Some(&Value::from(60_u64)));
    Ok(())
}

The memory log remains append-only. Reads are the latest projection of that history.

Operators

The Rust kernel implements the current core .me operators:

Use [kernel::Kernel::define_operator] to register aliases with existing operator kinds. Operator definitions replay through snapshots.

Paths And Plural Selectors

Paths are parsed by [kernel::IntoPath] and preserve .me selector grammar:

use this_me::kernel::{IntoPath, Kernel, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = "items[sku == 'A.1'].price".into_path()?;
    assert_eq!(path, vec!["items", "sku == 'A.1'", "price"]);

    let mut me = Kernel::new();
    me.postulate("items[].count", 3_u64)?;
    assert_eq!(me.read("items[].count"), Some(&Value::from(3_u64)));
    Ok(())
}

[] is grammar for plurality, not a Rust array type.

Eager And Lazy Derivations

Eager mode recomputes dependents when a source changes. Lazy mode keeps writes cheap and recomputes when a caller asks for a fresh read.

use this_me::kernel::{Kernel, RecomputeMode, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut me = Kernel::new();

    me.set_recompute_mode(RecomputeMode::Lazy);
    me.postulate("order.price", 10_u64)?;
    me.postulate("order.quantity", 2_u64)?;
    me.derive("order", "total", "price * quantity")?;

    me.postulate("order.price", 15_u64)?;

    assert_eq!(me.read("order.total"), Some(&Value::from(20_f64)));
    assert_eq!(me.read_fresh("order.total"), Some(Value::from(30_f64)));
    Ok(())
}

Since 0.3.1, lazy invalidation uses source path versions and stale-on-read checks instead of walking every subscriber at mutation time.

Runtime Host

KernelRuntime is the host-facing wrapper. It loads a kernel from a store, executes a write or me:// command, persists the snapshot, and returns the live events generated by that operation.

use this_me::runtime::{runtime_receipt_to_json, KernelRuntime};
use this_me::storage::JsonFileStore;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = JsonFileStore::new("/tmp/me-state.json");
    let mut runtime = KernelRuntime::load(store)?;

    let receipt = runtime.write_with_receipt(
        "apps.fulltrailer.home.count",
        3_u64,
    )?;

    println!("{}", runtime_receipt_to_json(&receipt));
    Ok(())
}

Events are live process state. Snapshots persist semantic memory, not transient notification queues.

Secret Scopes And Wrapped Audiences

Secret scopes move owner-readable branches out of the public projection:

use this_me::kernel::Kernel;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut me = Kernel::new();

    me.secret("wallet", "steel-door")?;
    me.postulate("wallet.balance", 100_u64)?;

    assert!(me.read("wallet.balance").is_some());
    assert!(me.read_public("wallet.balance").is_none());
    Ok(())
}

For audience-style key wrapping, use [kernel::generate_p256_key_pair], [kernel::wrap_secret_v1], and [kernel::unwrap_secret_v1].

Identity Proofs

The proof helpers derive an Ed25519 identity from a seed and sign a branch-scoped payload:

use this_me::kernel::{verify_ed25519_signature, Kernel, ProofInput};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let me = Kernel::with_compound_seed("jabellae", "secret");
    let proof = me.prove_with_timestamp(
        ProofInput {
            root_namespace: "local.netget".to_string(),
            challenge: Some("{\"nonce\":\"n-1\"}".to_string()),
        },
        1_700_000_000,
    )?;

    assert!(verify_ed25519_signature(
        &proof.public_key,
        &proof.message,
        &proof.signature
    ));
    Ok(())
}

JSON And Host Integration

The JSON codec helpers are re-exported from [kernel] for hosts that need stable JSON shapes:

• [kernel::kernel_value_to_json]
• [kernel::memory_to_json]
• [kernel::snapshot_to_json]
• [kernel::snapshot_from_json]
• [kernel::kernel_event_to_json]
• [kernel::execute_value_to_json]

Release Notes

• 0.3.3 - CLI about <expression> binding for context-scoped proofs.
• 0.3.2 - docs.rs/API polish and release documentation.
• 0.3.1 - source-versioned lazy invalidation; Run #002 mirror benchmark.
• 0.3.0 - first modern Rust kernel release on crates.io.

See the repository Rust/CHANGELOG.md for the human changelog.