# Changelog

This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).

## [Unreleased]

The four first fixes of the API audit: a person's proof of presence in one call, presence methods, fault codes on alerts, and one Stop. Then the modules `inventory`, `config`, `telemetry` and `diagnostics` (14 operations that answered `501`), the modules `software`, `artifacts` and `schedules` (15 more), and the modules `privacy`, `ai`, `memory` and `evolving` (17 more), with a real `GET /evolution`. Last, the modules `security`, `platform`, `provisioning`, `peers`, `batch` and `native`, `PUT /tending/allowlist`, and a Reasoning Gateway role for `POST /reason` (14 more): every operation of the API Index now has an implementation. Then the six second-priority fixes of the audit: one approval for a fleet command, commands to pushed systems behind NAT, the Basic owner key, grants and roles, polled values reaching the rules, and the effects of every change of ownership with `POST /provisioning/release`.

### Changed (one autonomy ceiling)

- **`GET` and `PUT /heart/v1/tending/autonomy`** (getTendingAutonomy, putTendingAutonomy) take the place of `GET`/`PUT /tending/mode`. A person sets one ceiling `{"max": 0..5}`; `autonomy.current` is the lowest of `max`, the promised level and what the system can do now; `mode` is read only and follows from `current` (0–2 `observe`, 3 `suggest`, 4–5 `act`). Lowering `max` needs only `heart.tend` and no approval, and to 2 or below it is Stop; raising it is `destructive`, needs `heart.admin` and comes only from a person (`403 capability-not-allowed` otherwise). Stop sets `max` to 2.
- `heart.control` and Pulse `autonomy` carry `max` and `current`; the event is `tending.autonomy.changed`; attestation claims carry `policies.autonomyMax`.
- Configuration: `Config::autonomy_max` and heartd `[core] autonomy_max` (default 5) set the starting ceiling.

### Changed (consistency fixes)

- **Action operations at every level that creates Actions** (API Standard 2): `GET /actions`, `GET /actions/{id}` and the decision answer at Connected and Full, and at Basic with any module that changes something; `501` only where no Action can exist. API Index and OpenAPI give them level `basic`.
- **`Idempotency-Key`** (API Standard 5.5): required on every non-read `POST` except `acknowledge`, `resolve`, `silence` and a decision (`postLifecycleOperation`, `postBrainRestore`, `postArrhythmias`, `createSubscription`, `postTendingProposals`, `postPresenceMethods` and the rest now check it); optional on `PUT`, `PATCH` and `DELETE`, where a key still returns a waiting Action on retry.
- **Silence** (API Standard 5.1): up to 30 days (a longer one answers `400`), `silencedUntil` set on the alerts of that code, and repeats are raised and listed but not notified. Maintenance mutes notifications the same way. `DELETE` removes `silencedUntil`.
- **Paging** (5.5): alerts and Actions newest first, with a cursor of the last item's time and ID; `nextCursor` is set when more remain.
- **Properties** (5.6): one above the caller's clearance answers `404` for reading and writing, checked before the gate; a read-only one `409 conflict`, also before the gate.
- **`PUT /brain/offline`**: the API Index scope is `heart.tend`; `heart.admin` also works, and turning auto mode on needs it (`403`).
- **Event names** (Part 3, Section 5.8): `system.lifecycle.started`, `.done`, `.failed`, `.cancelled`, `.maintenance-ended`, `.maintenance-window`, and `tending.silence.ended`.
- Native passthrough refused for `ai`, `peer` and `rule` answers `capability-not-allowed` (a caller's own request); `caller-not-allowed` is only for Proposals.
- heartd: a token's `act` chain makes the caller `ai` unless every actor is a HEART Gateway marked `heart_gateway: true`, so a person working through a Gateway stays a person (API Standard 8.2); a HEART Full Card without the `control` module is refused at start; the brain lease renewal sends `maxLeaseSec`. The `photo-editor` example lists `control`.
- `conformance/run.py` sends an `Idempotency-Key` on every non-read `POST` unless a test checks its absence.

### Added

- **One approval for a fleet command** (API Standard 13.3, Part 6 Section 8). The Gateway Action's digest is the fleet digest, over `{command, operation, arguments, physical, selector, targets, rollout}` with the targets sorted; a person approves it once with proof of presence. Each system then gets the operation with a new `actionId` and `presence` of method `fleet`, signed by the Gateway for that system alone. The Core (`heart_core::fleet`) accepts it as the approval of its own Action only if the Gateway key it pinned signed it, the system is a target, the request is exactly the one approved, it is at most 300 seconds old, and the approver is not the caller; a physical Action also needs `fleetPhysical`. Its gate, guards and Stop still apply, and the decision records `presenceMethod: fleet`. A fleet request may say `physical`. heartd: `[core] fleet_physical`, and `gateway_public_key` pins the key for fleet approvals too.
- **Command channel for pushed systems** (API Standard 9.3). With `[uplink] commands = true`, heartd pushes its Card without endpoints, long-polls the Gateway's inbox with `Prefer: wait`, and runs each command the Gateway signed (checked for signature, system, freshness of 60 seconds and replay) through its own API and gate, answering with a `heart.reply`. Forged, stale, replayed and misdirected commands are dropped unanswered and recorded as `security.command.refused`. The Gateway relays any request it cannot answer from what was pushed, waits up to 30 seconds, and answers `501` without a live channel.
- **Basic credential profile, the owner key** (API Standard 8.2). `[auth] owner_key_file` on a Basic Card: heartd makes a 256-bit owner key at first start, prints it once, keeps only its SHA-256 (mode 0600), compares in constant time, and treats its holder as the owner (`human`, `private`, the `owner` role's scopes). `heartd owner-key <config>` replaces it; the old key stops at once. A Card above Basic with an owner key is refused.
- **Module `access`** (API Standard 8.2, 13.2 rule 21): `GET /heart/v1/access/grants`, `PUT` and `DELETE /heart/v1/access/grants/{principal}`. Roles `owner`, `installer`, `maintainer`, `operator` and `viewer`, each a fixed set of scopes and a clearance (`heart_core::access::ROLES`). Granting or widening is `destructive`, narrowing or removing `write`, by a person only and never allowlisted; the first grant is an owner's, and the last owner grant stays. While any grant exists, heartd holds every caller to its own (`Core::apply_grant`); a client certificate maps through `Core::certificate_caller`. heartd's `[access]`.
- **`POST /heart/v1/provisioning/release`** (API Standard 13.2 rule 8): the owner gives the system up with proof of presence. It removes the owner, presence methods, grants, subscriptions, consents and schedules, cancels waiting Actions, and makes a new claim code shown only at the device.
- Tests: `tests/ownership.rs` (7 tests: grants and roles, fleet approvals with forged, stale, misdirected, self-approved and physical cases, release, factory reset and decommission, a rule and a Trial on polled values), unit tests for roles, grant widening, fleet digests, the fleet object and channel commands; one heartd test of the new sections; two end-to-end tests in `conformance/run.py` (release and claim again with grants; the owner key) and three in `conformance/gateway.py` (one approval across three systems, routed and pushed, with forged and stale approvals refused; a command through a pushed system's channel; forged, stale, replayed and misdirected commands dropped).

- **Module `security`** (API Standard 10.1 and 13.2 rule 7): `GET /heart/v1/security` (key version, identity key, owner, TLS, presence methods, update keys, audit size), `GET /heart/v1/security/attestation?nonce=` (evidence signed by the identity key over the caller's nonce, the software running with its digests, the configuration revision and the policy revisions; `internal` clearance), `POST /heart/v1/security/rotate` and `GET /heart/v1/audit`. Rotation is `destructive`: the host makes a new identity key and a rotation statement signed with the old one (`Effect::RotateKey`); for 7 days every Card carries `Heart-Key-Rotation`, the old key stays in the key set, and a second rotation answers `409`, so no peer is cut off. The audit log is bounded and chained by SHA-256 over RFC 8785 JSON: every request that may change something, refused reads, and denied, refused or expired Actions; never a body, and a native request only by its digest. Filters `category` and `outcome`, and `gap`.
- **Module `platform`**: `GET /heart/v1/platform` from the configuration and the host's reports of power, network and clock (`{"platform": {...}}` on the host feed, `Core::set_platform`), through the Valve.
- **Module `provisioning`** (13.2 rule 8): `POST /heart/v1/provisioning/claim` and `POST /heart/v1/provisioning/transfer`. A claim is proved by the code from the box, compared in constant time, and runs at once; after 5 wrong codes claims answer `429` for an hour, across restarts. It records the owner's key and issuer (`Core::owner_authority`), and the claim code is replaced and handed to the host (`Effect::ClaimCode`). A transfer needs the current owner's proof of presence; it moves the authority at once and removes presence methods, subscriptions, consents and schedules, cancels waiting Actions and replaces the claim code. A factory reset makes the system claimable again.
- **Module `peers`** (new 13.2 rule 20): `GET /heart/v1/peers`, `PUT` and `DELETE /heart/v1/peers/{id}`. Trusting a peer is `destructive`. A blocked peer is refused; a listed peer's clearance is capped by its entry (`public` while `pending`); `types` limits what the inbox takes from it. Messages stay data.
- **Module `batch`** (13.2 rule 9): `POST /heart/v1/batch`. Each item goes through the same route as a request sent alone: scope, clearance, peer trust, the gate with its own risk, its own `actionId` and proof of presence, and an `Idempotency-Key` made from the batch's. An item that needs the host waits for its effect, and the batch goes on. At most 100 items, `limits.maxBatch` or the module's `maxItems`; `stopOnError`; no batch in a batch.
- **Module `native`** (14.6): `POST /heart/v1/native/{protocol}`. Only a person with `heart.native` and `private` clearance; always `destructive`; `reason` required; only the protocols and targets listed; read only unless writes are turned on, and never a write to an address a custom definition marks `physical` or guards (`409 guard-failed`). `process` is never open.
- **`PUT /heart/v1/tending/allowlist`** (6.3, 13.2 rule 10): widening is `destructive`, narrowing `write`, and no allowlist covers it; entries are checked (initiators, envelopes, never a destructive or physical capability). The allowlist is kept in the state file until the configured one changes, and `heart.control` shows it with `approvalTimeoutSec`.
- **Reasoning Gateway** (7.2): `POST /heart/v1/reason` when `Config::modules.reasoning` is set. The Core checks the Reason request, refuses context above the Gateway's ceiling (`valve-blocked`), honours `modelPolicy` (pin, fallback, regions, `maxCostUsd`, `maxOutputTokens`), keeps a daily budget per caller, puts the owner's instructions in the system prompt and every context item and the conversation in escaped, marked blocks, and answers in the Reason format with provider, model, fallback and cost. The host adds the provider key (`Effect::Reason`); a provider's error text is never passed on.
- heartd: `[security]`, `[platform]` (with `/etc/os-release`, `/proc/meminfo` and a clock-sync file), `[provisioning]` (`claim_code_file`, rewritten mode 0600), `[peers]`, `[batch]`, `[native]` and `[reasoning_gateway]` (OpenAI-compatible and Anthropic Messages upstreams, keys from an environment variable or a file). The identity key rotates with `identity.key.previous` kept for the overlap and both keys in the key set; uplink pushes `heartkeyrotation`; the Gateway moves a pinned key on a valid rotation statement and on nothing else. Once claimed, only the owner's key signs accepted tokens. Each batch item's proof of presence is verified. In WASM, the new effects come out as `attest`, `rotate-key`, `claim-code` and `reason`.
- Tests: `tests/trust.rs` (16 tests) and unit tests for widening the allowlist, claim codes and thumbprints, native reads and writes, query decoding and prompt escaping; three heartd tests (the new sections, a rotated key reloaded, and the Reasoning Gateway against a local mock provider); nine new end-to-end tests in `conformance/run.py` and one in `conformance/gateway.py`, every reply checked against the schemas.


- **Module `privacy`** (API Standard 4 and 13.2 rule 6): `GET` and `PUT /heart/v1/valve/policy`, `GET` and `POST /heart/v1/consents`, `DELETE /heart/v1/consents/{id}`, `POST /heart/v1/data/export` and `POST /heart/v1/data/erase`. The Valve policy (`llmCeiling`, classifications, `retentionDays`) is the one the Valve filters with, kept in the state file until the Card's `valve` changes. Tightening it is `write`; loosening it is `destructive`. `llmCeiling: private` needs a granted consent for `model-provider`, and while none is granted private data does not reach a model; with `consentRequired: ["subscriber"]` the same holds for webhook deliveries. Withdrawing a consent filters the next transfer at once. The person, or a person with `heart.admin` acting for them, exports their data (Memory, consents, Actions, ratings, receipts of transfers made for them, Rhythm and log entries that name them, earlier erasures), filtered for the caller's clearance and bounded; with `artifacts`, as an artifact of kind `export` that expires. Erasing is `destructive`: it removes the person's Memory, consents, ratings, receipt links and stored exports, writes `[erased]` for their identifier in Actions, Rhythm and logs, and keeps only a record with a keyed digest of the identifier, which a later export shows.
- **Module `ai`** (API Standard 7 and 13.2 rule 18): `GET` and `PUT /heart/v1/ai/policy` and `GET /heart/v1/ai/usage`. The policy's modes, providers, regions, uses, daily and monthly budgets, the most per call and fallback apply to the next model call: a use or provider it does not allow is answered from rules, a call that would pass a budget answers `429 budget-exceeded`, and `modelPolicy` carries `allowFallback`, `maxCostUsd`, `regions` and the pin. Any change is `destructive` (API Standard 6.3); with the `brain` module the only mode is `org-proxy`. Usage per day (calls, tokens, cost, budget) is kept bounded and listed as `heart.usage`.
- **Module `memory`** (API Standard 8.1 and 13.2 rule 19): `GET /heart/v1/memory`, `POST /heart/v1/memory/search` and `DELETE /heart/v1/memory/{id}`. Messages received at the inbox are kept as short-term items at their own level (at least `internal`), so inbox data can be read back; how each Trial ended is kept as a long-term item. An item above the caller's clearance is not listed, found or deleted. Bounded, expiring, and within the Valve policy's `retentionDays`.
- **Module `evolving`** (API Standard 11 and 13.2 rule 11): `PUT /heart/v1/evolution/pins/{purpose}`, `POST /heart/v1/evolution/rollback`, `GET /heart/v1/evolution/lessons` and `POST /heart/v1/feedback`. A pin change is `destructive` and runs the system's regression suite first (`Effect::Regression`); the model is pinned only if it passes, and the Rhythm records `evolving.model.adopted` or `evolving.model.rejected`. The suite's Action is cancellable, and Stop cancels it. Rollback (`write`) returns to the previous pin once. Lessons are the Playbooks learned from Trials. Ratings of an Action, an answer, a Trial or a lesson are kept bounded. `GET /heart/v1/evolution` now shows the pin for each purpose with its regression result, the candidates tested and how many lessons exist; the pin for each use is sent with each model call.
- heartd: `[privacy]`, `[ai]`, `[memory]` and `[evolving]` (with `regression_command`); `heart_core::log::BoundedLog::values_mut`. In WASM, the new effect comes out as `regression`.
- Tests: `tests/rights.rs` (23 tests) and unit tests for erasing a word, loosening the Valve and widening the AI policy; the hostile-request property in `tests/prop_robust.rs` reaches the four modules; five new end-to-end tests in `conformance/run.py`, every reply checked against the schemas.

- **Module `software`** (API Standard 13.2 rule 4): `GET /heart/v1/software`, `/software/sbom`, `/software/updates`, `/software/updates/{id}`, `POST /software/updates` and `POST /software/rollback`. The host lists what the update source offers (`Effect::UpdateCheck`); the Core verifies each manifest's Ed25519 signature over its RFC 8785 JSON against `Config::modules.software.keys`, then the downloaded payload's size and SHA-256 (`Effect::UpdateDownload`), and only then asks the host to install (`Effect::UpdateInstall`). Unsigned, forged and tampered updates answer `403 signature-invalid`, raise `security.update.refused` and install nothing. Installing is `destructive`; the Action is cancellable, and stopped by Stop, until it installs. A failed install is rolled back. `POST /software/rollback` (`Effect::Rollback`) returns to the version before the last update. heartd's `[software]` reads an SBOM, a directory or `https` update source, `update_keys`, `install_command` and `rollback_command`, and lists itself as a package.
- **Module `artifacts`** (API Standard 13.2 rule 16): `GET` and `POST /heart/v1/artifacts`, `GET` and `DELETE /heart/v1/artifacts/{id}` and `GET /heart/v1/artifacts/{id}/content`. Uploads carry the file in base64 with `kind`, `mediaType`, `privacy`, `sha256` and `expiresAt`; the store is bounded in files, total bytes and file size; a file above the caller's clearance is not listed and answers `404`; content is checked against its digest before it is sent, with `ETag`, and heartd answers one byte range with `206`. The bytes live with the host (`Effect::ArtifactPut`, `ArtifactGet`, `ArtifactDelete`); heartd keeps them in `[artifacts] dir` and removes files nothing refers to at start.
- **Module `schedules`** (API Standard 6.3 and 13.2 rule 17): `GET` and `POST /heart/v1/schedules`, `GET` and `DELETE /heart/v1/schedules/{id}`. A schedule holds one operation at a time (`at`) or repeatedly (five-field `cron`, in UTC), or declares a maintenance window, and keeps its author with their scopes and clearance. Creating it has the risk of what it schedules, at least `write`, and `destructive` for a maintenance window; no allowlist covers it; one made by `ai`, `peer` or `rule` is `proposed` until a person approves it. Each run is a new Action with `scheduleId`, passed through the gate as the author at that moment: a destructive run waits for a person, a peer's or AI's run follows the mode and the allowlist as they are then, and under Stop no run that changes anything starts. Runs are recorded and bounded; a run too late is `missed`. `delaySec` on a lifecycle request now becomes a schedule.
- `Idempotency-Key` is required on the new writes, and accepted on every `DELETE`: a retry of one that waits for approval returns the same Action.
- `heart_core::codec` (base64); `Core::artifact_ids`, `Core::installed_version`; `heart_core::time::civil_from_days`. In WASM, the new effects come out as `update-check`, `update-download`, `update-install`, `rollback`, `artifact-put`, `artifact-get` and `artifact-delete`.
- Tests: `tests/manage.rs` (21 tests) and unit tests for cron, payload names and base64; two heartd tests of the new sections and of byte ranges; seven new end-to-end tests in `conformance/run.py`, with a signed update source, every reply checked against the schemas.

- **Module `inventory`** (API Standard 13.2 rule 14): `GET /heart/v1/components` (parents before children, paged), `GET /heart/v1/components/{id}` and `GET /heart/v1/dependencies`, from `Config::modules.inventory`. A part's `status` comes from its open alerts. `Core::dependency_status` raises or resolves `connectivity.dependency-unreachable`; heartd's `[inventory]` probes each dependency's `host:port`.
- **Module `config`** (API Standard 13.2 rule 2): `GET` and `PATCH /heart/v1/config` (JSON Merge Patch), `POST /heart/v1/config/validate`, `GET /heart/v1/config/history` and `POST /heart/v1/config/rollback`. Settings declare type, range, default and privacy; the whole result is checked before anyone approves it; every change is a revision, applied first by the host (`Effect::ApplyConfig`); history is bounded and says `gap`. Writes pass the gate (`write`), take `actionId` and `presence`, match allowlist entries `"PATCH /heart/v1/config"` with an envelope per setting, and are refused for `ai`, `peer` and `rule` after Stop. `never-share` settings are never returned or changed through the API. heartd's `[config]` writes a settings file and runs an apply command.
- **Module `telemetry`** (API Standard 13.2 rule 15): `GET /heart/v1/metrics`, `GET /heart/v1/metrics/{name}` with `from`, `to` and `step`, and `GET /heart/v1/logs` with `since`, `until`, `minSeverity`, `component` and a Server-Sent Events stream. Metrics come from vitals and numeric properties, logs from every Rhythm event and from the host (`Core::host_log`, `{"log"}` on the host feed, heartd's `log_file` and `journald_unit`). Both are bounded, and secrets are removed from a line before it is kept.
- **Module `diagnostics`** (API Standard 13.2 rule 5): `GET /heart/v1/diagnostics`, `POST /heart/v1/diagnostics/{test}` and `POST /heart/v1/diagnostics/bundle`. Tests run on the host (`Effect::Diagnostic`) with a time limit; a disruptive one is `write`, passes the gate, answers with its Action and is cancelled by Stop when `cancellable`. A support bundle takes `since`, `until`, `include` and `maxBytes`, is filtered for the caller's clearance and never holds secrets or `never-share` data. heartd's `[diagnostics]` runs programs or native requests.
- `Idempotency-Key` on these writes is required, kept per principal and operation, answered with the original response, `422` for another body and `409` while the first still runs.
- `Config::modules`; `Core::config_values`, `Core::host_log`, `Core::dependency_status`. In WASM, `heart_start` takes `modules`, and the new effects come out as `config` and `diagnostic`.
- Tests: `tests/modules.rs` (22 tests); the hostile-request property in `tests/prop_robust.rs` reaches the four modules; three heartd tests of the new sections; eleven new end-to-end tests in `conformance/run.py`, every reply checked against the schemas.

- **A person's own request in one call** (API Standard 6.3, rules 1 and 3). Every request that can create an Action takes `actionId`, a UUID the client chooses; the Action gets that ID, so the client computes the digest before sending and sends `presence` for it in the same request. A person's destructive or physical request with a proof that verifies runs at once (`200` with the finished Action, or `202` while it runs); a proof for another digest is refused with `403 presence-invalid` and creates nothing; `presence` without `actionId` is `400`; a used `actionId` is `409 conflict`; a retry with the same `Idempotency-Key` returns the original Action. For an operation that is not a capability, the Action's `result` holds the operation's own answer.
- **Module `presence`** (API Standard 13.2 rule 13): `GET`, `POST /heart/v1/presence/methods` and `DELETE /heart/v1/presence/methods/{id}`. Enrolling a WebAuthn passkey is destructive and passes the gate: proved by one of the person's own passkeys in the same request, or approved by another person. While nothing is enrolled, the first passkey is proved by presence at the device: a request through the local interface (`Caller::local`). Listing never returns key material. Removing needs no proof, except that the last method stays when `card.presence.requireMethod` is set; a configured passkey is removed in the configuration. `Core::passkeys`, `Core::seed_passkeys` and `Core::passkey_used` serve the host.
- `heartd`: passkeys in `[presence]` are seeded into the Core (`source: "config"`); enrolled ones are kept in the state file and verified too, with `lastUsedAt`. With `[presence]`, the Card offers module `presence` and `card.presence.rpId`.
- `/serve`: "stop the conveyor" maps to the named thing's `halt` capability (a capability named `halt`, or ending in `.halt` or `_halt`), which waits for confirmation like any physical action. Only "stop", "stop autonomy", "stop all automatic actions" and the like run Stop. A thing with no `halt` gets a question, never Stop.
- Tests: `tests/presence.rs` (5 tests); in `tests/behaviour.rs`, one call with proof, `PUT /tending/mode` observe as Stop, halt versus Stop in `/serve`, and fault codes; in `tests/prop_gate.rs`, the property `a_person_alone_runs_their_own_request_with_proof_in_one_call`. The conformance suite has three new end-to-end tests and does every person's own change in one call.

### Changed

- **Polled values reach the rules** (Core Standard 4.3 and 7.3): a value the Core reads itself (Modbus, `process`) feeds Trials' `expect` and `undoIf`, the Tending rules that watch it, and its metric, as a host-feed value does.
- **Ownership changes have one table of effects** (API Standard 13.2 rule 8). A transfer also removes grants. A factory reset also removes peers, erases Memory, consents, ratings, receipt links, erasure records and every other Action, and makes a new claim code; a decommission does the same and can never be claimed. `Effect::ClaimCode` gains `owner_changed`, so a host renews its HEART Hub identity; heartd also makes a new Basic owner key. In WASM, `claim-code` carries `ownerChanged`.
- Specification: API Standard 6.3 (presence method `fleet`; granting access is an authority change), 8.2 (roles, grants, the owner key), 9.3 (the command channel; a pushed system with one may claim Full), 13.1 (modules `access` and `provisioning`), 13.2 rules 8 and 21, and 13.3; Part 4 Sections 6.5, 6.6 and 9.5; Part 6 Sections 3.2, 4.1 and 8; Part 9 tests `P4-OWNER-KEY`, `P4-ACCESS-GRANT`, `P4-GATEWAY-CHANNEL`, `P6-FLEET-ONE-APPROVAL` and `P6-OWNERSHIP`. New message type `heart.grant` (`grant.schema.json`); `fleet` in the presence methods; `fleetPhysical` in `control.schema.json`; `physical` in `fleet-request.schema.json`; `digest` and `physical` in `fleet.schema.json`; module `access`. The API index has 124 operations (four new).
- **Rotating the identity key is `destructive`** (API Standard 13.1): it changes whom every peer trusts.
- For 7 days after a rotation a Card response carries `Heart-Key-Rotation`. `heart.control` now carries the allowlist and `approvalTimeoutSec`.
- Specification: API Standard 7.2 rule 6 (a Reasoning Gateway keeps the keys and a daily budget per caller), 10.1 rule 7 (the statement's header carries the old key; the old key stays in the key set), 13.2 rules 7 to 10 (what `security`, `provisioning`, `batch` and the allowlist answer, and the effects of a claim, a transfer and a factory reset), new rule 20 (`peers`) and 14.6 rule 6 (listed protocols and targets; writes off, and never to guarded or physical addresses). The OpenAPI file gives attestation its `nonce`, the audit log its filters, rotation and peers their bodies, and the batch its answer; `security.schema.json` gains `identity`, `owner`, `claimable`, `tls`, `presenceMethods`, `updateKeys` and `auditEntries`, and `peer.schema.json` gains `types` and `updatedAt`.

- **`PUT /valve/policy` takes its risk from the change** (API Standard 6.3, 13.1 and 13.2 rule 6): loosening is `destructive`, tightening `write`. Any change to the AI policy stays `destructive`, as 6.3 says. `POST /data/erase` no longer requires `presence` in its body: without it, the request waits for another person's approval, like any destructive request.
- The daily budget, the most per call and the model pin come from the AI policy and the pins kept in the state file; the Pulse leaves out `budgetUsdToday` when no daily budget is set.
- Specification: API Standard 6.3 lists loosening the Valve policy among changes to authority; 8.1, 11 and 13.2 rules 6 and 11 say how `privacy` and `evolving` answer, and new rules 18 and 19 cover `ai` and `memory`. The OpenAPI file types the bodies of `putValvePolicy`, `postConsents`, `postDataExport`, `putAiPolicy`, `postMemorySearch`, `postEvolutionRollback` and `postFeedback`. New message types `heart.usage` and `heart.export` (`usage.schema.json`, `export.schema.json`); `aipolicy.schema.json` gains `revision`, `uses` and `maxCallUsd`; `consent.schema.json` `expiresAt` and `withdrawnAt`; `memory.schema.json` `privacy` and `subject`, with `summary` taking the item's level; `evolution.schema.json` a pin's `version` and a candidate's `purpose`, `version` and `requestedAt`; a classification path may name `brain`, `usage` and `export`.

- **The approver is never the initiator, a person included** (API Standard 6.3; Part 6, Section 3.2). The Core and the Gateway no longer let a person approve their own Action; they may still deny or cancel it. `prop_gate.rs::a_person_never_approves_their_own_action_afterwards` runs again.
- **One Stop** (API Standard 13.4): `PUT /heart/v1/tending/mode` with `observe` has exactly the effects of `POST /heart/v1/tending/stop`, risk `read` and scope `heart.tend`; any other mode also needs `heart.admin`.
- **Fault codes on alerts** (Part 3, Section 5): every alert carries `code`, and `kind` alongside where an old kind fits. `POST /heart/v1/arrhythmias` reads `code`, with `explanation` and `component`; a body with only an old `kind` is turned into its code. Silences and de-duplication go by code. A Playbook that raises an old kind raises its code. A failed undo raises `system.undo-failed`; the 80% budget warning raises `ai.budget-near-limit`; the Gateway's flatline raises `system.flatline`.
- An Action for an API operation is named `"METHOD /path"` with the path as sent, and its `arguments` are the request body without `actionId` and `presence`. A physical property's write is physical.
- `heartd` reads `presence` in the body of `POST`, `PUT`, `PATCH` and `DELETE`. The same assertion sent again for the same digest is a retry, not a replay.
- Example rules raise dotted fault codes (`connectivity.dependency-unreachable`, `performance.memory-exhausted`, `storage.write-failed`).
- The API index has 120 operations (three new).
- An Action for a `per-item` operation (a lifecycle operation, a disruptive test) records the risk its request was given, `write` or `destructive`, never `per-item`, which `action.schema.json` does not allow.
- **Installing an update is `destructive`** (API Standard 13.1), as Part 2 and Part 6 already said of installing firmware. `POST /software/rollback` stays `write`.
- The gate's risk of an operation is worked out once, in `operation_gate`, which a schedule also uses for the operation it holds. An Action created by the gate keeps the initiator's scopes and clearance, for a schedule it creates.
- Specification: API Standard 5.5 lets a `DELETE` carry an `Idempotency-Key`; 13.2 rule 4 says how `software` answers, new rules 16 and 17 cover `artifacts` and `schedules`, 6.3 says no allowlist covers creating a schedule, and rule 3.7 says how `delaySec` is gated. The OpenAPI file types the bodies of `postSoftwareUpdates`, `postSoftwareRollback`, `postArtifacts` and `postSchedules`, adds the `Range` header and every `DELETE`'s optional key; `update.schema.json`, `schedule.schema.json`, `software.schema.json` and `action.schema.json` (`scheduleId`) gain the fields these modules return.
- Specification: API Standard 13.2 rules 2 and 5 say how `config` and `diagnostics` answer, and new rules 14 and 15 cover `inventory` and `telemetry`. The OpenAPI file gives `getLogs` its filters, `postConfigRollback` its body, `postConfigValidate` its answer and `postDiagnosticsBundle` its optional body; `diagnostic.schema.json` has `bundle`. The API index and privacy table are rebuilt from them.

## [0.6.0] - 2026-11-12

Decision D36 of the HEART machines roadmap: the brain switch. A Command Center gives the Core its brain on a lease, signs every answer, and can take the brain away at once.

### Added

- Module `brain` (API Standard 7.4, Core Standard 7.8), in `heart_core::brain`:
  - **Leases.** `Core::brain_lease` accepts a lease only if it is signed with the pinned Command Center key (Ed25519, `card.brain.commandCenter.key`), is for this system, and is newer than the last one. Its length is at most `card.brain.maxLeaseSec` (default 300), counted on the Core's clock from receipt, so a wrong wall clock can only shorten it, and a clock that goes back ends it.
  - **Checked answers.** A Proposal, or a Reason response for `/ask` and `/serve`, is used only if it is signed for a request this Core sent (`brain_sent` keeps their digests), under the current lease, by a model and for a use the lease names. A lease-only local model's answers are accepted unsigned, as rule 6 allows. A rejected answer is recorded as `ai.answer-rejected` and counted.
  - **Brainless.** When the lease ends, is dropped or is refused, waiting Proposals and `ai` Actions are cancelled, a running brain Trial is undone, and adopted Playbooks and people's own work go on. Pulse `autonomy.limitedBy` becomes `brain-cut`, capped at A4, and `ai.lease-expired` or `ai.brain-revoked` is raised.
  - **Signals.** `Core::brain_signal` and `POST /heart/v1/brain/signal` accept `brain-off`, `revoke-model`, `revoke-use` and `autonomy-stop` only if signed, for this system, at most 300 seconds old, and not seen before. They can only lower risk.
  - **Restore.** After a cut (a signal or the self-cut, not a lease that ran out), a system with `restoreNeedsOwner` (the default when any capability is physical) refuses leases until a person approves `POST /heart/v1/brain/restore`, which is destructive.
  - **Auto mode.** `PUT /heart/v1/brain/offline` is destructive to turn on and lowers risk to turn off. With the link lost (`Core::brain_link(false)`), a lease's `offline` block is used for at most its `maxSec`, capped by `card.brain.offline.maxSec`, with uses narrowing by `stepDown`. It ends at once when the link returns.
  - **Self-cut.** The Core cuts its own brain after `limits.brainRefusalsPerHour` (default 10) refused Proposals, or 3 rejected answers, within an hour.
  - `GET /heart/v1/brain` shows the state; `brain_renewal`, `brain_renew_in_ms` and `brain_lease_id` serve the host.
- `heartd`: `[brain]` (`command_center`, `key`, `device_id`, `device_key_file`, `max_lease_sec`, `restore_needs_owner`, `offline_max_sec`).
  - It renews the lease when a third is left, passes signals and leases to the Core, and reports link loss.
  - Model calls go to `/cc/v1/devices/{id}/reason`. `[brain]` and `[model]` cannot both be set: no model keys on the device.
- Tests:
  - `tests/brain.rs` has 16 tests.
  - `tests/prop_brain.rs` has 2 properties: no answer is used after its lease, or without a good signature, in any order of messages; no signal raises anything.
- The API index has 117 operations (four new).

## [0.5.0] - 2026-11-12

Decisions D29 and D30 of the HEART machines roadmap: lifecycle requests that say how, what and when, and cancelling running work.

### Added

- Module `lifecycle` (API Standard 13.2 rule 3): `GET /heart/v1/lifecycle` and `POST /heart/v1/lifecycle/{operation}` for `restart`, `shutdown`, `sleep`, `wake`, `drain`, `reload`, `power-cycle`, `safe-mode`, `maintenance-on`, `maintenance-off`, `reset-config`, `reset-network`, `clear-data`, `factory-reset`, `decommission` and vendor `x-` operations. The request is checked against `lifecycle-request.schema.json` before anyone is asked to approve it; unknown fields are refused.
- The risk comes from the request and can only rise: a forced restart, a power cycle, partial and factory resets, and a shutdown of a system nothing can wake remotely (`card.lifecycle.wakeSources`) are `destructive`.
- The Core hands a checked, approved operation to its host as `Effect::Lifecycle`; the Action carries `nextReachableAt` (or `null` and `nextReachableNote`), names the operation as `"POST /heart/v1/lifecycle/<op>"` in `operation` (D19), and a restart of the HEART or the system first undoes a running Trial.
- Maintenance ends by itself at `maintenanceUntil` (`durationSec` required, at most `limits.maxMaintenanceSec`).
- `heartd`: `[lifecycle.<operation>]` runs a program without a shell (the request in `HEART_LIFECYCLE_REQUEST`) or a native request; only configured operations are offered, and the Card lists them. A graceful operation that runs out of time fails; it is never forced.
- Cancelling running work (API Standard 6.3 rule 5): `cancel` on an `approved` or `running` Action with `cancellable: true` moves it to `cancelling`; the host checks `Core::cancel_requested` at its safe points and answers `{"cancelled": true}`. A cancel needs no proof of presence and never undoes what was done; a running Action that is not cancellable answers `409`. Stop asks running cancellable work to stop.
- `PATCH /heart/v1/subscriptions/{id}` pauses and resumes a webhook; `DELETE /heart/v1/arrhythmias/{id}/silence` ends a silence early.
- Action status `refused` counts as ended.

### Fixed

- `POST /heart/v1/arrhythmias/{id}/silence` reads `durationSec` and `silencedUntil`, as the OpenAPI file says (it read only `forSec`).

- Gateway fleet commands (API Standard 13.3, Part 6 Section 8): `GET` and `POST /heart/v1/fleet/commands`, `GET /heart/v1/fleet/commands/{id}` and `POST /heart/v1/fleet/commands/{id}/{pause|resume|cancel}`, with scope `heart.fleet`. Targets come from the selector (systems, labels, profile, status); the rollout is staged, the first stage is never more than 10% of the targets, and the defaults are 5% per stage, one failure and 300 seconds. A command that is not a `GET` is a Gateway Action, approved with `POST /heart/v1/actions/{id}/decision` and a passkey (`[presence]` in the Gateway configuration) by a person other than a non-human initiator. A rollout pauses at its failure limit; `pause` and `cancel` need no approval and touch no further system; `resume` is a new Action that needs a new approval, and its failure limit counts from the resume. Each system receives the operation as the sender, with an `Idempotency-Key`, and applies its own gate; a `202` from a system counts as accepted, not failed.
- `heart_core::jcs` (RFC 8785) and `Core::message` are public, for hosts that answer some operations themselves.

## [0.4.0] - 2026-11-12

Follows the reviewed HEART Core Standard 1.0 Sections 4.3 and 7.1 to 7.7.

### Security

- One approval covers a Trial's whole plan: the first Action's digest now includes every step's arguments (`plan`) and the values the undo restores (`restore`). Later steps and the undo carry `approvedBy` (the first Action) and pass the guards, not the gate.
- The Core reads the values to restore itself (its last applied values, or `Core::setting` from the product). `POST /heart/v1/tending/proposals` refuses a body with `previous` (`400`), and a Proposal whose current values are unknown is refused `422 cannot-undo`.
- The allowlist is per initiator: entries are `{target, initiators, envelope}` as in `heart.control`. A bare string is now an entry for `rule` only (it used to cover `ai` and `peer` too).
- A brain's Proposal uses the allowlist only at Autonomy Level 5 (`autonomy_level`, Pulse `autonomy.current`). In `suggest` every non-read Action from `rule`, `ai` or `peer` asks a person; in `observe` they are refused `409 autonomy-stopped`, including a peer's.
- A rule runs only if `enabled` is true and `status` is `adopted`. A rule with no `status` is `proposed`. A rule runs a physical capability only with `adoptedPhysical: true` (the older `physical: true` is still read).

### Fixed (found by the property tests, TESTING.md)

- Action digests are SHA-256 over RFC 8785 JSON, as Part 6, Section 3.2 says: numbers are written the ECMAScript way (`2.0` as `2`, `1e21` as `1e+21`) and keys sorted by UTF-16. They used serde_json's text, so a screen recomputing the digest got a different one for whole-number values.
- Guards (`whenStates`, `whenStatus`, `requiresMaintenance`, `minIntervalSec`, `maxPerHour`) are checked just before sending, for every Action: the first step of a Trial and an Action approved later were sent without them.
- A Trial is kept only when each `expect` check held by its own `withinSec`; before, one check could hold late as long as the longest `withinSec` had not passed.
- A check never uses samples from before the step it judges, also for `value`: an old sample could keep a Trial.
- A restart while a Trial is `undoing` keeps it `undoing` (it went back to `running`).
- A learned Playbook's fix is refused when the Core does not know the current value of every argument it changes (D10); the undo could not have restored them.
- In `observe`, a Playbook may still run a `read` Action; only non-read Actions are refused.
- A `PUT` of a custom definition or a Playbook whose body is a JSON array, string, number or boolean is refused `400`; it panicked the Core.
- A model reply that is not a JSON object no longer panics `POST /ask` (it is treated as a failed call), and a negative reported cost no longer refunds the daily budget.
- The Valve reads a `dynamic` field's level from its `privacy` sibling even when an owner classification hides that sibling (it fell back to private), and a Card view no longer gains `capabilities: null`.

### Changed (schema alignment)

- Interlocks are `common#/check` objects (`{"signal", "op", "value"}`); the older text form `tank.level > 10` is still read. A boolean reads as 1 or 0.
- Pulse `tending.lastAction` is the id of the last Action (or null), not a capability name.
- Card `shares` in the examples and the Gateway hold only message types and `public`/`internal`/`private`.

### Changed

- Envelopes name each argument: `{"arguments": {"<name>": {min, max, maxStep}}, maxPerDay, cooldownSec}`. An argument it does not name never changes automatically. `maxPerDay` counts automatic Trials in any rolling 24 hours, and `cooldownSec` runs from the end of the last automatic Trial. `Config::envelopes` is gone: envelopes live in the allowlist.
- Trial states are `awaiting-approval`, `running`, `undoing`, `kept`, `undone`, `refused`, `stopped` and `undo-failed`, as published. An undo refused by a guard ends `undo-failed`. Stop ends a waiting Trial `stopped`.
- A Trial is kept only when every `expect` check held and the longest `undoIf` `withinSec` passed. Checks take `windowSec`.
- Statistics: `value` replaces `last`, `stddev` is added, and `trend` is a least-squares slope per minute.
- Proposal refusals carry the standard codes: `400 invalid-request`, `403 caller-not-allowed`, `404 not-found`, `409 conflict`, `409 autonomy-stopped`, `422 out-of-range`, `422 cannot-undo`. `Core::propose` takes no `previous` and returns `Refusal`. The last step must equal the Proposal's arguments.
- Learned Playbooks trigger on the opposite of the first `expect` check (a check in `when`), carry an envelope of the values the Trial set or restored, and get `reviewBy` (one year) only when a person adopts them. `==` and `!=` are not learned. Playbook Trials carry `ruleId` and no `proposalId`.
- Rules use the published form: `when` is a check or `{event, component, count, windowSec}`, and `then.raise` is `{code, severity, summary}`. Older rule files are converted on load.
- Pulse carries `autonomy`. Actions carry `expiresAt` (`approval_timeout_sec`). Trials are never shown to public callers.
- `postTendingProposals` is never a `/serve` target.

## [0.3.0] - 2026-11-12

### Added

- `POST /heart/v1/tending/proposals` (scope `heart.propose`): a brain delivers a Proposal over the API. It becomes a gated Action with initiator `ai` and `onBehalfOf` the brain. Delivering changes nothing by itself.
- `GET /heart/v1/tending/trials/{id}`: one Trial, as `heart.trial`.

## [0.2.0] - 2026-11-12

### Security

Meets Security Advisory HEART-2026-001 (see `spec/HEART-Security-Advisory-2026-001.md` in the HEART specification).

- C1: approvals, and a person's destructive or physical actions, need a WebAuthn proof of presence over the Action's digest (`[presence]`). Tokens with `act` are treated as `ai` and cannot approve.
- C2: adding a Playbook and raising autonomy are destructive. Only an administrator adopts a Playbook, and it runs only its own capability, and a physical one only if adopted as physical.
- C3: tokens must name this system in `aud`. Key-bound tokens need a DPoP proof, and off loopback every token must be bound. The Gateway no longer forwards tokens: it signs caller headers (RFC 9421), and systems trust headers only when signed (`gateway_public_key`) or from `gateway_uid` on the socket.
- C4: every system has an identity key and sends `Heart-Card-Signature` with its Card. The Gateway requires a signed Card to join at Connected or Full, and pins the key.
- H1: receipts are salted commitments. The salt travels with the data.

### Added

- Trials (Core Standard, Sections 7.1 to 7.7): `Core::propose` turns a brain's Proposal into a gated Action; each step and the undo are Actions; `tick` watches `expect` and `undoIf`; stop and restart undo a running Trial; envelopes (`Config::envelopes`) limit automatic changes; a kept fix becomes a proposed learned Playbook, which runs as a Trial when adopted and is suspended after two undos or at its review date. `Core::consultation` builds features, never samples. New module `heart_core::trial`; `time::parse_rfc3339`.
- HEART Gateway: `heartd gateway`, with routed and pushed systems, Flatline alerts and persistence.
- `[uplink]`: a system announces itself to a Gateway, and keeps doing so.
- Host feed: the product reports its own events, metrics and state.
- `heart_core::address`: resolves `heart://` addresses.
- WASM: `heart_report`, structured effects, custom definitions, rules and bring-your-own-key models.
- Examples: air-conditioner controller, photo editor, Gateway.
- `scripts/dev-token.py` for development keys and tokens.

### Changed

- Operations outside the Card's claimed level and modules now return `501`.
- If Recall matches nothing, a model chooses among the product's own commands.

### Fixed

- A model could pass off an invented value as a `default`. Defaults are now checked against the definition.

## [0.1.0] - 2026-11-07

### Added

- `heart-core`: Valve, approval gate, Recall tier, serving, Tending, custom definitions.
- `heartd`: HTTP over TLS and Unix sockets on ports 43278 and 7685, webhooks, Modbus TCP and process adapters, atomic state, watchdog.
- `heart-wasm`: the Core for browsers.
- Pump station example and an end-to-end conformance suite.