Compare a proposed patch against its baseline using the repository’s own evaluators.
dream-engine is a Rust library workspace and offline command line for evidence-gated repository improvement. A host freezes an experiment, asks a model for a patch and evaluates the baseline and candidate on the same testbed. The gate returns a verdict from measured evidence without calling a model. The host owns scheduling, model access, notifications and publication.
Use it to build nightly maintenance, compare candidate implementations, replay an experiment or enforce protected paths before applying a patch. An accepted result can become a draft pull request. Acceptance does not establish deployment readiness: that depends on the evaluators you configured and the behaviour they cover.
The design is deliberately cautious about what counts as evidence. An
evaluator that is missing, silent, blocked, timed out or failing vetoes the
change. A broken testbed is reported as BLOCKED-ENV, which is a different
verdict from a bad patch, so infrastructure trouble is never read as a verdict
on the model. A candidate may not touch the files that decide whether it
passes (ADR-DE-003).
sequenceDiagram
participant H as Host driver
participant S as Source reader
participant M as Model adapter
participant E as Evaluator runner
participant G as Pure gate
participant F as Forge adapter
H->>H: Freeze manifest and experiment identity
H->>E: Evaluate baseline
H->>S: Read tracked source at the selected revision
S-->>H: Bounded source packet and refusal record
H->>M: Request one candidate patch
M-->>H: Patch
H->>H: Check protected paths before applying
H->>E: Evaluate candidate on the same testbed
H->>G: Paired results and bound receipts
G-->>H: ACCEPT / REJECT / INCONCLUSIVE / BLOCKED-ENV
opt Accepted and publication configured
H->>F: Publish through the configured policy
end
The engine freezes an experiment manifest (baseline revision, tree hash, the
sha256 of each evaluator command, model identity and a digest of the config)
atomically before any model call. The run id is a pure function of that
manifest, so a restart resumes the same experiment, and a baseline that has
diverged is archived rather than overwritten. It then evaluates the baseline,
calls the model once, applies the patch, evaluates the candidate on the same
testbed, and gates the pair. A run moves through ManifestFrozen,
BaselineEvaluated, ModelCalled, CandidateEvaluated, Gated, Persisted and Complete. A finished night is terminal: a restart or a changed HEAD never repeats it
(ADR-DE-007). The gate
returns ACCEPT, REJECT, INCONCLUSIVE or BLOCKED-ENV. The full account
is in docs/concepts.md.
The statistics are checked against reference values computed independently in exact arithmetic: nine wins out of ten gives an exact one-sided binomial p of 11/1024, and a Wilson lower bound for eight of ten at z = 1.96 is 0.4902.
Add a library:
cargo add pairwise-gate
cargo add failure-fingerprintInstall the command line and run its checks in a clone:
cargo install dream-cli # installs the `dream` binary
git clone https://github.com/DreamLab-AI/dream-engine
cd dream-engine
dream validate # checks ./dream.config.json
dream guard check --patch my.diff --config dream.config.json
dream witness stamp --report README.md --commit "$(git rev-parse HEAD)"dream guard check exits 0 when the patch is clear, 1 when it touches a
protected path and 2 when it could not run. dream replay verify RUN_DIR
re-judges a recorded night and dream ledger verify PATH checks a ledger.
There is no dream run: the nightly driver is the host's, built from
dream-core.
To build and test from source:
cargo test --workspace --lockedConfiguration for a Rust repository is in docs/guide/configuring-a-repo.md.
Reviewed 21 October 2026 against source 64e8324. The workspace declares version 0.2.0; individual crate versions and consumer pins are separate. Use the crate manifests and your host's lockfile when choosing an API version. This review did not run a live model-to-GitHub experiment.
The 0.2.0 source-reading API adds GatherInput::with_requested: requested files are selected before planner picks and evidence-mentioned paths. Requests can reserve at most half the file slots and half the rendered byte budget. The reader checks them against the tracked tree and denylist and records honoured and refused requests. The host stores and expires requests; the library does not interpret last night's report or ask an operator for files. See ADR-DE-008 and source.rs.
Integration boundaries and unfinished behaviour
What is not here yet: the nightly driver itself (a host supplies it by
implementing the seams), TrainDev with held-out dev evaluators wired into the
nightly path, and post-publish recheck with ledger-driven rollback. The forge
step of automerge is unit-tested against a stub but has not been exercised
against real GitHub, and dream_core::persist::publish is the only entry point
that applies the automerge policy: a host that opens its pull requests through
Forge::publish_draft directly never merges anything, whatever autoMerge says.
A finished night is terminal, but publishing is not an exactly-once distributed transaction: crash recovery does not reconcile every external forge outcome. Read ADR-DE-007 before designing retry policy.
VisionFlow documents the estate's self-improvement loop. This repository owns the reusable, permissively licensed gate and execution components. Agentbox owns its product-specific host and AGPL integration with identity, relay and notification services. A source pin or published crate does not establish that a running host has been rebuilt with it.
This is an independent Rust implementation. The former TypeScript tracking fork is historical lineage; it is not this workspace's implementation or release identity.
docs/README.md is the index. The decisions are in docs/adr/. If you are coming from the TypeScript fork, start with the migration note. A comparison with a related system is in docs/COMPARISON.md.
The nightly, evidence-gated, config-driven design descends from ruvnet/dream-machine by rUv. This repository is an independent Rust implementation of that design lineage. No source text from that project is copied. Its MIT licence is reproduced in NOTICE as credit and as a precaution.
MIT OR Apache-2.0, at your option: LICENSE-MIT and
LICENSE-APACHE. The adapter that connects the engine to a
private forum and Nostr deployment is AGPL-3.0-only, lives in the product that
consumes the engine, and is not part of this repository
(ADR-DE-002).
Diagram corpus (citation-verified, with a register of tensions and debt): docs/diagrams.