# HEART Core (Rust)

Reference implementation of the [HEART Core Standard](spec/README.md): 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 `Effect`s, which is why the same code runs in a daemon, in a browser and on bare metal.

## Quick start

```sh
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`](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`](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`](CONFORMANCE.md) lists exactly what is implemented, and what is not.

## Testing

```sh
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](TESTING.md).

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). To report a vulnerability, see [`SECURITY.md`](SECURITY.md).

## License

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