HEART Core (Rust)#

Reading tracks3 Advanced
Advanced: the reference implementation of HEART Full. Which track am I?

Reference implementation of the HEART Core Standard: a small embedded AI runtime that understands the whole HEART API and uses it to serve people, other systems and the product it lives in.

Status: early reference implementation (0.1.0). It passes its own conformance suite against simulated devices and a mock model. It has not been tested on physical hardware, with a real language model, or by an independent party. Do not use it in a safety function or a real-time control loop.

What it does#

Serves the HEART API at HEART Full level, on port 43278 with fallback to 7685, over TLS or a Unix socket.
Filters every outgoing field through the Valve, and records a receipt for what it sends to a model.
Understands plain requests through POST /heart/v1/serve, with no model needed for direct requests.
Sends every state change through the approval gate. A model can propose, but it cannot act.
Maps product commands to real protocols with custom definitions. Modbus TCP and argument-list processes are included.
Looks after itself: detects faults, raises alerts, explains and escalates, with no network.
Runs as a HEART Gateway with heartd gateway: one port for many systems, routed live over Unix sockets or TLS, or served from what they push. A device behind NAT takes commands through the channel it holds open to the Gateway, and a fleet command needs one person's approval, not one per device.
Takes the product's own events through a local host feed: one line of JSON per event.

Layout#

Path	What it is
`crates/heart-core`	All the logic. `no_std` with `alloc`, and no I/O, so one codebase runs anywhere.
`crates/heartd`	Linux daemon: HTTP, TLS, Unix sockets, webhooks, adapters, storage and watchdog.
`crates/heart-wasm`	The same Core for browsers, with no bindings tool required.
`examples/pump-station`	A complete configuration, with a Modbus simulator.
`examples/ac-controller`	An air-conditioner controller, used by the first guide.
`examples/photo-editor`	A photo editor embedding the Core, used by the second guide.
`examples/gateway`	A HEART Gateway configuration.
`conformance`	End-to-end suite and its latest results.
`spec/1.0`	Copy of the published schemas, index and test vectors.

heart-core never touches the outside world. It asks its host to do things through Effects, which is why the same code runs in a daemon, in a browser and on bare metal.

Quick start#

cargo build --release -p heartd

# Terminal 1: a simulated pump
python3 examples/pump-station/simulator.py

# Terminal 2: the Core
./target/release/heartd run examples/pump-station/heartd.toml

# Terminal 3: ask it how it is
curl -s http://127.0.0.1:43278/.well-known/heart-card.json
curl -s http://127.0.0.1:43278/heart/v1/pulse

Anything beyond public reads needs an access token: see docs/CONFIGURATION.md.

Other commands:

Command	Purpose
`heartd check <config>`	Validate a configuration
`heartd supervise <config>`	Run under the built-in watchdog
`heartd gateway <config>`	Run a HEART Gateway (see `examples/gateway`)

Results#

From conformance/run.py on a 2-core Linux x86-64 virtual machine. Full output is in conformance/results.json.

Measure	Result
End-to-end tests, daemon	37 of 37 passed
End-to-end tests, Gateway	19 of 19 passed
`heartd` binary, including the Gateway	2.9 MB
WASM module	430 KB
Memory at rest	5.6 MB
Memory after a 20,000-request flood	16 to 19 MB across runs
Gateway with 2,000 systems	78 MB, about 36 KB per system
Gateway, pushed Pulse read over TLS, median	3.0 to 5.0 ms across runs
`GET /pulse` over TLS, median	3.1 to 5.2 ms across runs
Sustained inbox rate	1,600 to 2,000 requests/s across runs

These come from one machine and simulated devices. Treat them as a baseline, not as a benchmark.

Standards compliance#

CONFORMANCE.md lists exactly what is implemented, and what is not.

Testing#

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

# End to end (needs Python packages jsonschema[format] and cryptography, plus openssl and node)
cargo build --release -p heartd
cargo build --release -p heart-wasm --target wasm32-unknown-unknown
python3 conformance/run.py
python3 conformance/gateway.py
node conformance/wasm.mjs

The Valve, gate and Recall tier are tested against vectors produced by the independent Python tools in the specification.

Property and fuzz tests (thousands of random cases per rule; HEART_PROP_CASES sets how many) are described in TESTING.md.

Contributing#

See CONTRIBUTING.md. To report a vulnerability, see SECURITY.md.

License#

Licensed under either of Apache License 2.0 or MIT, at your option. Unless you state otherwise, any contribution you submit is licensed the same way, without further terms.