awrecover

Docs · Source · pip install awrecover · The Aither World

The Aither World is an operating system for agents — a Linux you can hand to one, the runtimes it works in, and the tools it works with. awnix is the Linux underneath it; awrecover is one of its 66 bricks — each installs on its own, runs offline, and needs no account.

Start here: Snapshot one directory, break it, restore it, diff it.

Snapshot a directory, and get it back — with proof that you can.

```bash
pip install awrecover

awrecover snapshot ./run --store .snaps --label pre-finetune
awrecover verify   --store .snaps --label pre-finetune      # RESTORES it, to a scratch dir
awrecover restore  --store .snaps --label pre-finetune --dest ./run

Python 3.10+. awrecover needs awshare, which it installs with; add pip install "awshare[seal]" if you want snapshots signed as well as digested.

Deliberately thin

A snapshot is an awshare bundle. Archiving, digesting, atomic writes, path containment, refusing symlinks and bounding expansion are all awshare's job and are not reimplemented here. awrecover adds exactly two things awshare has no opinion about:

• a label index, so you say pre-finetune instead of remembering a digest
• a restore that fully lands or does not land at all

If you want a bundle, use awshare. You want awrecover when you will be coming back for it under a name, possibly in a hurry.

Two rules it exists to enforce

A backup nobody has restored is a hypothesis

verify does not check that the archive exists, or that it is a plausible size. Those pass for a snapshot of the wrong directory, a truncated one, and one taken of nothing at all. It restores into a scratch directory, through the same code path a real restore uses, and throws the result away.

```bash
awrecover verify --store .snaps --label pre-finetune
# 0  restorable — this really came back
# 1  checked, and it is NOT restorable
# 2  could not check at all

Exit 1 and exit 2 stay separate for the reason they always must: collapsing them turns "I could not check this" into "it checked out".

There is a narrower version of the same trap inside verify itself. A label can be present in the index while its manifest is gone — so the index says the backup exists and the backup does not. That is reported as its own error, in those words: the index is a claim; the archive is the backup.

A half-restore is worse than no restore

It destroys the working state and fails to deliver the snapshot. So restore never writes into the target:

```
1. unpack into a staging dir BESIDE dest      (a failure here changes nothing)
2. verify the staged tree
3. move dest aside     -> .awrecover-replaced-<label>-<pid>
4. rename staging      -> dest

The window where neither tree is in place is one rename wide. And the tree it replaced is moved aside, not deleted — if the swap fails, your old state is still there under a name you can find. Pass --discard-replaced when you are sure and want the space back.

If anything fails before step 3, the error says Nothing was changed, and it is telling the truth.

Everything it does

```python
import awrecover
from pathlib import Path

awrecover.snapshot(Path("run"), Path(".snaps"), "pre-finetune")
awrecover.verify(Path(".snaps"), "pre-finetune")          # raises if it will not restore
r = awrecover.restore(Path(".snaps"), "pre-finetune", Path("run"))
r["replaced"]   # where your previous tree went

awrecover.latest(Path(".snaps"))        # the most recent Snapshot, or None
awrecover.list_snapshots(Path(".snaps"))

--key on verify and restore is passed through to awshare, so a snapshot can be required to come from a known publisher and not merely to be intact. Integrity and provenance are two questions; awshare answers the first and awseal the second.

Licence

Apache-2.0.

The aw family

Standalone tools that share one idea: replace something you would otherwise have to trust with something you can check.

Each installs on its own, works offline, and needs no account.

awnix is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.

The Aitherium ecosystem

Every repository here is public. Each publishes an aither-manifest.json beside its page, so any surface can read every sibling's — the network is browsable from any node in it.