Concepts

How it works

Envidence records normalized machine facts, compares a before and after window, and ranks the differences that are relevant to a failure. It reports evidence, not a guaranteed cause.

The building blocks

Object	What it represents
Snapshot	A normalized record of the machine at one point in time.
Run	A command, its working directory, exit code, duration, bounded output, and the snapshots around it.
Case	An investigation attached to a failed run, with ranked findings, changes, and a status.
Baseline	A known-good snapshot used as a reference when you ask what changed.
Change	One difference between two snapshots, including its category, origin, and before and after values.

Snapshots are not backups

A snapshot stores the machine layer around your project, such as the path used to resolve a tool, a global package version, a listening port, or a config hash. It does not store your source tree. Git remains responsible for source changes.

Most facts are normalized before they are compared. Full state is kept in content-addressed blobs and the searchable metadata lives in SQLite inside the local store.

Fast and full profiles

Full snapshots collect the broadest set of machine facts. Fast snapshots skip some slow collectors and are used by evd watch by default. Use evd snap --full or evd watch --full when the failure could involve services, tasks, programs, or other full-only collectors.

Command windows

evd watch -- <command> takes a snapshot before the command, runs it, and takes another snapshot after it. The two snapshots define the command window.

Each change gets an origin label:

observed-during means the change appeared by the time the post-command snapshot was taken. It can still have been caused by another process.
pre-existing means the change was already present relative to the reference state before the command window began.

A change can also be marked volatile. That means the fact changes as part of normal machine activity, such as free disk space or a short-lived port. Volatile changes are hidden unless you ask for them.

A change in the window is not automatically the cause

A package cache, an editor extension, or a background updater can write during the same window. The origin label narrows the time range. It does not prove causality.

How a reference is chosen

When evd watch records a run, it selects a reference and stores it with the run. It prefers, in order:

The last successful run of the same command in the same project.
The active baseline.
The most recent snapshot before the command window.

If none of those exists, the pre-command snapshot is used. You can choose a different reference with evd why --since 2h or evd why --since SNAP-.... A bad reference produces a misleading diff, so check the reference line before trusting the findings.

How findings are ranked

Each difference receives a score based on its type and context. The ranking combines:

The base weight of the change category.
Whether the project or command uses the affected tool or package.
Whether the change appeared during the command window or was already present.
Signals in the command output, including stderr text.
Historical correlation, when the store has enough samples.

Historical correlation is smoothed and gated by a minimum sample count. A new store leans more on base rules and project relevance. That means early findings are useful leads, not a mature statistical model.

Review the raw changes

Inspect the evidence

evd diff
evd diff --category packages,path
evd diff --search typescript
evd why --since 2h --all

evd diff compares the last two snapshots. You can also pass two snapshot IDs, labels, or prefixes. --category limits the output to categories such as packages, path, env, or services. --all includes volatile changes.

Use evd fingerprint when you want a stable digest of tracked, non-volatile machine state without a diff.

From evidence to a plan

A rollback plan is built from supported changes in a case or snapshot. It contains typed actions for things Envidence can reverse, such as an environment variable, a PATH entry, a global package version, a config file, or a service state. Anything outside that set becomes a manual step.

Preconditions are checked against current state before apply. If the machine no longer matches the plan, Envidence refuses to continue. See Rollback for the full safety flow.

What a result can mean

A confident "no non-volatile machine changes" result is useful. It means the evidence points back to code, a dependency install that did not affect these collectors, an external service, or a cause outside the recorded scope. It does not mean the failure is invalid.

When findings exist, check the top items first, then review the full change list. The limitations page covers the known gaps in collection and causality.