# Rust .me
Rust ground for the modern `.me` semantic kernel.
This crate is the Rust port of the TypeScript `.me` kernel, kept faithful to the
same semantic model: append-only memories, hash-chain integrity, path grammar,
operators, secret/noise scopes, derivations, inspection, proofs, key wrapping,
snapshots, and live runtime events.
The goal is not to invent a second `.me`. The goal is to carry the same kernel
meaning into a smaller, stricter runtime that can eventually live closer to
hardware: a daemon, a local gateway, a Raspberry Pi, a vehicle computer, an
embedded agent, or a future `monad.ai` host.
## What Exists
The Rust kernel currently includes:
- hash-chained semantic memory,
- public and owner projections,
- canonical path parsing with selectors such as `items[]`, `items[0]`, and
`items[field >= 10]`,
- the main `.me` operators:
- `@` identity,
- `_` secret scope,
- `~` noise scope,
- `__` pointer,
- `=` derivation,
- `?` query/collect,
- `-` remove/tombstone,
- operator registry and semantic replay,
- eager and lazy derivation recompute modes,
- `inspect()` and `explain()` traces,
- secret value encryption using the v3 blob material model,
- WrappedSecretV1 key wrapping with P-256 ECDH and AES-GCM,
- Ed25519 `.prove()` identity proofs,
- canonical `me://` execute dispatch,
- JSON snapshot storage,
- a reusable `KernelRuntime` host with write-through persistence,
- live runtime events with path filtering,
- runtime receipts for host integrations,
- a small `me` CLI,
- Rust contract tests against TypeScript fixtures,
- and release-mode benchmark binaries.
## Install And Verify
From this directory:
```bash
cargo fmt --check
cargo check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
```
That is the standard gate for this crate. A green run means formatting,
compilation, semantic contracts, CLI contracts, fixture parity, and clippy all
pass.
## Quick Kernel Example
```rust
use this_me::kernel::{Kernel, Value};
let mut me = Kernel::new();
me.postulate("profile.name", "Jabellae")?;
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)));
```
The memory log remains append-only. Reads are the latest projection of that
history.
## Runtime Host
`Kernel` is the semantic core. `KernelRuntime<S>` is the host wrapper: it loads a
kernel from a `MemoryStore`, performs writes or `me://` executions, persists the
snapshot, and returns live events.
```rust
use this_me::runtime::{runtime_receipt_to_json, KernelRuntime};
use this_me::storage::JsonFileStore;
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,
)?;
let json = runtime_receipt_to_json(&receipt);
println!("{json}");
```
Receipts have a stable host-facing shape:
```json
{
"result": "... operation result ...",
"events": [
{
"path": ["apps", "fulltrailer", "home", "count"],
"operator": null,
"value": 3.0,
"memoryHash": "..."
}
]
}
```
That shape is meant for HTTP/WS hosts: execute once, persist once, broadcast the
events generated by that operation.
## CLI
Use the local CLI against an optional JSON snapshot file:
```bash
cargo run -- --state /tmp/me-state.json write profile.name '"Jabellae"'
cargo run -- --state /tmp/me-state.json read profile.name
cargo run -- --state /tmp/me-state.json exec me://self:write/wallet.income 1000
cargo run -- --state /tmp/me-state.json inspect profile
cargo run -- --state /tmp/me-state.json explain wallet.total
cargo run -- --state /tmp/me-state.json snapshot
```
Without `--state`, the CLI runs an ephemeral kernel. With `--state`, it uses the
same `KernelRuntime` host path used by embedders.
Produce a branch-scoped proof:
```bash
cargo run -- --who jabellae --secret 'correct horse battery staple' prove local.netget '{"nonce":"n-1"}'
```
Equivalent seed mode:
```bash
cargo run -- --seed '<seed>' --expression jabellae prove local.netget '{"nonce":"n-1"}'
```
## Events
Runtime events are live process state. They are intentionally not persisted in
snapshots. Snapshots persist semantic memory, not transient notification queues.
Drain all events:
```bash
cargo run -- --state /tmp/me-state.json exec me://kernel:drain/events
```
Read or drain events matching a path:
```bash
cargo run -- --state /tmp/me-state.json exec me://kernel:read/events/apps.fulltrailer
cargo run -- --state /tmp/me-state.json exec me://kernel:drain/events/apps.fulltrailer
```
Filters use the same ancestor/descendant rule as monad's NRP path stream:
subscribing to `apps.fulltrailer` receives changes at that path, below it, or
replacing one of its ancestors.
## Storage
`JsonFileStore` persists owner snapshots as JSON:
```rust
use this_me::storage::{JsonFileStore, MemoryStore};
let store = JsonFileStore::new("/tmp/me-state.json");
let kernel = store.load_kernel()?;
store.save_kernel(&kernel)?;
```
Hydration verifies the memory hash chain. Tampered snapshots fail closed.
## Cryptography
The Rust port includes two cryptographic surfaces:
- Ed25519 proofs for `.prove()` identity signatures.
- WrappedSecretV1 using P-256 ECDH key agreement and AES-GCM wrapping.
Secret branches use the same v3 material model as the TypeScript kernel fixtures
covered by the test suite.
## Contracts
The test suite is contract-first. Important files:
- `tests/axioms_contract.rs` - algebraic invariants.
- `tests/kernel_contract.rs` - core kernel behavior.
- `tests/path_contract.rs` - path and selector grammar.
- `tests/execute_contract.rs` - canonical `me://` dispatch.
- `tests/event_contract.rs` - live event queue and filters.
- `tests/runtime_contract.rs` - host persistence, receipts, event behavior.
- `tests/storage_contract.rs` - JSON snapshot storage.
- `tests/proof_contract.rs` - Ed25519 proofs.
- `tests/keyspace_contract.rs` - keyspace manifest and wrapped keys.
- `tests/wrapped_secret_contract.rs` - WrappedSecretV1 crypto.
- `tests/typescript_fixture_contract.rs` - parity with TypeScript memory fixtures.
## Benchmarks
See [BENCHMARKS.md](BENCHMARKS.md) for the benchmark map.
Run benchmarks in release mode:
```bash
cargo run --release --bin bench-ok
cargo run --release --bin bench-sustained
cargo run --release --bin bench-fanout
cargo run --release --bin bench-cold-warm
cargo run --release --bin bench-explain-overhead
cargo run --release --bin bench-secret-scope
cargo run --release --bin bench-push-pull
cargo run --release --bin bench-secret-push-pull
```
Benchmarks are not hard pass/fail thresholds yet. They are there to keep the
shape honest: O(k) recompute behavior, sustained mutation, fan-out, cold/warm
hydration, explain overhead, secret cost, and eager/lazy tradeoffs.
## Module Map
```txt
src/kernel/mod.rs core memory, operators, projections
src/kernel/path.rs path and selector grammar
src/kernel/evaluator.rs derivation expression evaluator
src/kernel/execute.rs me:// dispatch
src/kernel/json.rs JSON codecs
src/kernel/proof.rs Ed25519 proof support
src/kernel/secret_material.rs secret/noise material derivation
src/kernel/wrapped_secret.rs WrappedSecretV1
src/storage.rs MemoryStore + JsonFileStore
src/runtime.rs KernelRuntime host + receipts
src/me_uri.rs canonical me:// URI parser/projection
src/main.rs me CLI
```
## Current Status
This is now a real Rust kernel, not boilerplate.
It is ready for deeper parity testing and host integration work. It is not yet a
drop-in replacement for the TypeScript kernel inside `monad.ai`; that next phase
needs an explicit integration layer, packaging decision, and HTTP/WS host
surface.
The rule remains simple: Rust can improve mechanics, memory safety, and runtime
shape, but it must not change `.me` meaning to chase a number.