# 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/`](https://neurons-me.github.io/.me/Rust/).
## Quick Start
```rust
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:
| `@` | [`kernel::Kernel::claim_identity`], [`kernel::Kernel::identity`] | identity marker |
| `_` | [`kernel::Kernel::secret`] | secret branch scope |
| `~` | [`kernel::Kernel::noise`] | noise boundary |
| `__` | [`kernel::Kernel::pointer`] | structural pointer |
| `=` | [`kernel::Kernel::derive`] | live derivation |
| `?` | [`kernel::Kernel::query`] | collect/query memory |
| `-` | [`kernel::Kernel::remove`] | tombstone/remove projection |
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:
```rust
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.
```rust
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.
```rust,no_run
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:
```rust
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:
```rust
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`](https://github.com/neurons-me/.me/blob/main/Rust/CHANGELOG.md)
for the human changelog.