Harmos

build v0.2.0-32-g3a80c85

Harmos is a journal-as-truth runtime for Rust applications. It holds an application's working state as one plain value and admits changes through one ordered journal. The current state is the origin with those changes applied in order:

state = origin + the entries recorded since it

The journal is the source of truth, not a log copied from some other state. That distinction gives replay a precise job. Recovery rebuilds state from the same entries that produced it the first time. Undo appends an inverse. Reads carry the position they observed. Storage, projections, and audit consumers fold the same order without becoming another authority.

What the Runtime Owns

Harmos owns the boundaries whose correctness depends on one order:

• checked, atomic state transitions through a single writer;
• typed records beside those transitions in the same position space;
• replay, undo, redo, historical reads, and recovery;
• storage consumers and the visible distance between applied and durable work;
• high-rate typed Streams that stay outside history while retaining state context and exact loss accounting;
• finite Jobs, resident Services, deterministic simulation, and optional direct guest and sidecar boundaries.

The application still owns its state types, transaction rules, file formats, storage policy, external effects, and user-facing errors. Harmos supplies the order and the contracts around it.

When It Fits

Use harmos when state must be reconstructed exactly, edits need durable identity, or several facilities must agree on what happened and when. Editors, instrument hosts, configuration tools, and other stateful applications benefit when audit, recovery, selective undo, and live observation should all derive from the same committed history.

Do not use it as a general database, a message broker, or a high-rate sample store. Data with no effect on replay belongs in a derived view, an ordinary file, or Streams. A service whose state is already authoritatively owned by an external database should not copy that authority into an in-memory journal without a deliberate boundary.

Find Your Path

Getting Started reaches the first committed change and positioned read from compiling example code.

Vocabulary is the one-word-one-meaning map — journal, position, track, window, lease, draft. Several of these words mean something else in other runtimes, so keep it open while you read.

The Tutorials walk the runtime in six sections, each adding what the last did not have:

• Build Your First App — an in-memory app with undo.
• Storage — durability.
• Work — supervised work and isolation.
• History & Evidence — reads beneath the live edge.
• Artifacts — directly loaded guests and sidecars.
• Prove & Ship — proof and release.

The chapter files are numbered in reading order.

The Reference maps the runtime top-down and then crosses each crate boundary. It names every accepted core export from the census and links to deployed rustdoc for signatures.

The Developer section is for changing harmos rather than using it: the stable wire formats, and one design page per facility stating what was decided and what the build deliberately does not do.

The guide's complete schematic editor lives in examples/minischematic/ and runs with mise run run:minischematic. The guide embeds its source, and its behavioral tests exercise that same library.