backupproof 0.2.0__tar.gz

backupproof-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calas Automations Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backupproof-0.2.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: backupproof
+Version: 0.2.0
+Summary: Backup restore testing: restore the latest restic/borg/Proxmox backup into a throwaway target, boot it, run smoke checks, report PASS or FAIL with proof
+Author: Calas Automations Inc.
+License: MIT
+Keywords: backup,restore,restic,borg,proxmox,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# backupproof — we prove your backup weekly
+
+The #1 backup failure is not "no backup" — it's "backup never
+tested, restore fails." backupproof takes the latest restic, borg,
+or Proxmox backup, restores it into a throwaway target, verifies
+it, and reports PASS or FAIL **with proof**: which checks passed,
+which failed, and the evidence for each.
+
+One verdict, three smoke packs only — web, DB, files. Nothing else.
+
+**What "verify" means depends on the source — and the report says
+which (v0.2.0 honesty fix):** restic/borg backups are file-level,
+so the restored *files* are content-checked; there is no disk
+image to boot, and the PASS line says so. Proxmox backups restore
+into a throwaway VMID on the Proxmox host and are probed there
+(web pack via a probe URL). A PASS line never claims a boot that
+did not happen.
+
+## Install (local)
+
+```sh
+pip install .
+# or, for development:
+pip install -e .
+# or without installing, from this directory:
+PYTHONPATH=. python3 -m backupproof --help
+```
+
+Requires Python 3.9+. Stdlib only — no third-party dependencies,
+no keys, no accounts, no telemetry, no phone-home.
+
+## Usage
+
+```sh
+# The verdict: latest backup -> restore -> boot -> smoke -> PASS/FAIL
+backupproof run --config backupproof.json
+backupproof run --config backupproof.json --json --report proof.json
+
+# List backups for a source (newest first)
+backupproof list --config backupproof.json
+backupproof list --source-type restic --repo /srv/backups --json
+
+# Validate a config without restoring or booting anything
+backupproof validate --config backupproof.json
+
+# Write example config + fixture files (runnable: run --config <dir>/config.json)
+backupproof init --output backupproof-examples
+```
+
+Exit codes, CI-usable: **0 = PASS, 1 = FAIL (a check failed),
+2 = ERROR** (no backup found, restore failure, boot failure or
+timeout, bad config, missing tool). `--json` works on all commands.
+
+### Config
+
+A JSON file naming the source and the smoke checks:
+
+```json
+{
+  "source": {"type": "restic", "repo": "/srv/backups"},
+  "checks": {
+    "web": [{"name": "homepage", "path": "/",
+             "expect_status": 200, "expect_contains": "Welcome"}],
+    "db": [{"name": "users table", "db_file": "app.db",
+            "query": "SELECT count(*) FROM users", "expect_rows_min": 1}],
+    "files": [{"name": "config", "path": "etc/app.conf",
+               "sha256": "<hex>", "size_min": 10}]
+  }
+}
+```
+
+Source types: `restic` (`repo`), `borg` (`repo`), `proxmox`
+(`dump_dir` — a vzdump directory), `fixture` (`dir` — see below).
+DB checks run the query against a SQLite file in the restored
+target (stdlib `sqlite3`), or run a `command` (e.g. `psql`) and
+check its output. Web checks fetch a real URL: `path` is resolved
+against the served/restored target's base URL, or give a full `url`.
+Files checks take `path` plus any of `sha256`, `size_min`,
+`size_max`, `size_exact`, and `max_age_days`: the restored file's
+modification time (as preserved by restic/borg) must be within N
+days of the **backup's timestamp**, not of now — catches a nightly
+dump file that stopped updating inside a fresh backup (`FILE_STALE`,
+both dates reported). An unknown backup timestamp is a FAIL, never
+a pass.
+Optional `"mode": "0640"` and `"owner": "postgres"` compare the
+restored file's permission bits and owning user (`pwd`)
+(`FILE_MODE_MISMATCH` / `FILE_OWNER_MISMATCH`). On non-POSIX
+hosts (Windows) both are a FAIL "not verifiable on this OS", never
+a pass. Note: restic and borg restore file ownership only when run
+as root; run as another user, restored files belong to that user.
+
+### Per-source fields
+
+- `restic` / `borg`: `repo` (required). Optional `serve_dir` —
+  a directory inside the restored tree (e.g. `"webroot"`) that
+  backupproof serves over real localhost HTTP, so web checks can
+  hit the *restored* content (labelled "restored content, not a
+  VM" in the report). Without `serve_dir`, web checks need full
+  `url` values. **Passwords pass through the operator's env:**
+  `RESTIC_PASSWORD` for restic, `BORG_PASSPHRASE` for borg —
+  backupproof adds no credential handling of its own.
+- `restic` / `borg` optional `"restore": "checked-paths"`
+  (default `"full"`): restore only the paths the checks read —
+  files-check `path`s, db `db_file`s and `serve_dir` (restic:
+  repeated `--include /<path>`; borg: `extract` with path
+  arguments). The restore line and the PASS line then say
+  `partial (N paths) — only checked paths restored; the rest of
+  the backup was not restore-tested`. A config with no
+  path-bearing check is a `CONFIG_ERROR`. Opt-in only: a partial
+  restore does not prove the whole backup restores.
+- `proxmox`: `dump_dir` (required), `throwaway_vmid` (REQUIRED —
+  backupproof refuses to guess a VMID it will later destroy),
+  `storage` (default `"local"`). The restore runs `qmrestore` /
+  `pct restore` into the throwaway VMID, starts it, probes it
+  (with `--probe-url`), then stops and destroys **only that
+  VMID**. A pre-flight `qm/pct status <vmid>` refuses the run if
+  the VMID already exists. **Pack guard:** db/files packs cannot
+  verify a VM's filesystem from the host, so a Proxmox real-mode
+  config containing them is an ERROR (`PROXMOX_PACK_UNSUPPORTED`,
+  exit 2) naming the packs and the remedy (web checks with
+  `--probe-url`, or run backupproof inside the guest) — packs are
+  never silently dropped and PASSed.
+
+### Repository integrity step (opt-in)
+
+`--integrity` runs `restic check` (add `--read-data-subset PCT`
+to also read that share of the pack data) or `borg check
+--repository-only` (`--verify-data` for `borg check
+--verify-data`) **before** restoring. A failed check is an ERROR
+(`INTEGRITY_FAILED`, exit 2) carrying the tool's last 20 output
+lines; a passed one adds `integrity: {tool, args, ok}` to the
+report. Cost warning: restic's documentation notes that reading
+pack data downloads it from the repository, which is slow and can
+cost money on cloud storage. Plain `restic check` (no subset)
+checks structure only. Use a small subset, not full reads, weekly.
+
+### Dead-man's-switch ping (opt-in)
+
+`--ping-url URL` sends one HTTP GET after the verdict: `URL` on
+PASS, `URL/fail` on FAIL or ERROR — the healthchecks.io
+convention, so a missed weekly run also alerts. 10-second
+timeout. A ping failure prints a warning on stderr and never
+changes the exit code. Nothing is sent unless the flag is given.
+
+### Staleness gate
+
+Top-level `max_age_days` (or `--max-age-days`, CLI wins): when
+the latest backup is older than that, the verdict carries a
+warning. With `--fail-on-stale`, the run refuses outright
+(`STALE_BACKUP`, exit 2) before restoring anything. A backup
+whose timestamp is missing or unparseable warns ("cannot
+determine age") and never fails on staleness alone.
+
+### Which packs verify what, per source
+
+| Source | web pack | db pack | files pack |
+|---|---|---|---|
+| restic / borg (real) | served restored tree (`serve_dir`) or explicit URL | restored files | restored files |
+| proxmox (real) | booted VM via probe URL | **refused** (pack guard) | **refused** (pack guard) |
+| fixture (simulated) | served fixture webroot over real HTTP | fixture tree | fixture tree |
+
+The report's `verified against:` line states this per run, and
+`--report` JSON carries `boot_kind`, `boot_probed`,
+`verified_against`, `warnings`, `restore_partial`, `integrity`
+and `restore_seconds` fields. `restore_seconds` is the wall time
+of the restore step only (not boot or probe) — RTO evidence; the
+text shows `restore: … in 37.2s`. In simulated (fixture) mode it
+times the fixture copy and is labelled `(simulated)`.
+
+A run with no checks configured is an ERROR, never a PASS. A
+check that cannot be verified is a FAIL, never skipped silently.
+
+### Example PASS output
+
+```
+PASS (simulated): backup restores and boots in simulation, all smoke checks passed
+  backup: fixture snap-20261028 (2026-10-28T03:00:00Z)
+  mode: simulated (SIMULATED restore/boot — not a real VM boot)
+  restore: SIMULATED restore into /tmp/backupproof-yoi9_m9l/restored (3 files copied from fixture)
+  boot: SIMULATED boot completed in 42s (fixture boot.json; not a real VM boot); serving webroot webroot at http://127.0.0.1:34147
+  verified against: restored fixture tree (web pack served over real HTTP from the restored webroot)
+  PASS [web] homepage: HTTP 200, body contains 'Welcome'
+  PASS [db] users: query returned 1 row(s): [('alice',)]
+  PASS [files] config: app.conf: 10 bytes, sha256 matches
+```
+
+A real restic/borg run reports instead:
+`PASS: backup restores, all smoke checks passed (file-level backup — content verified, no VM boot)` —
+and a Proxmox run with no probe URL reports
+`PASS: backup restores, VM started (unprobed), all smoke checks passed`.
+
+### Example FAIL output (failing check named)
+
+Change the restored homepage so it no longer contains "Welcome"
+and the same run reports:
+
+```
+FAIL: 1 of 3 smoke check(s) failed
+  backup: fixture snap-20261028 (2026-10-28T03:00:00Z)
+  mode: simulated (SIMULATED restore/boot — not a real VM boot)
+  restore: SIMULATED restore into /tmp/backupproof-y8b2y4d3/restored (3 files copied from fixture)
+  boot: SIMULATED boot completed in 42s (fixture boot.json; not a real VM boot); serving webroot webroot at http://127.0.0.1:45629
+  FAIL [web] homepage (WEB_CONTENT_MISSING): HTTP 200 but body lacks 'Welcome' (first 200 chars: 'Something else entirely\n')
+  PASS [db] users: query returned 1 row(s): [('alice',)]
+  PASS [files] config: app.conf: 10 bytes, sha256 matches
+```
+
+Named failures: web — `WEB_UNREACHABLE`, `WEB_STATUS_MISMATCH`,
+`WEB_CONTENT_MISSING`; DB — `DB_FILE_MISSING`, `DB_QUERY_FAILED`,
+`DB_NO_ROWS`, `DB_CONTENT_MISSING`, `DB_COMMAND_FAILED`; files —
+`FILE_MISSING`, `FILE_SIZE_MISMATCH`, `FILE_HASH_MISMATCH`,
+`FILE_STALE`, `FILE_MODE_MISMATCH`, `FILE_OWNER_MISMATCH`.
+Errors (exit 2): `NO_BACKUP_FOUND`, `RESTORE_FAILED`,
+`BOOT_FAILED`, `BOOT_TIMEOUT`, `MISSING_TOOL`, `CONFIG_ERROR`,
+`INTEGRITY_FAILED`.
+
+### Try it (fixture example, no backup tools needed)
+
+```sh
+backupproof run --config examples/config.json
+```
+
+The example fixture restores a small tree (webroot, `app.conf`,
+SQLite `app.db`) and simulates boot while genuinely serving the
+webroot over real localhost HTTP, so the web check is really
+exercised.
+
+## Weekly cadence (doc example only — no built scheduler)
+
+backupproof has no daemon and no built-in scheduler by design.
+Run it weekly from cron or a systemd timer. Cron example (Sundays
+03:30, proof report kept per run):
+
+```cron
+30 3 * * 0 /usr/local/bin/backupproof run --config /etc/backupproof.json --report /var/log/backupproof/proof-$(date +\%F).json >> /var/log/backupproof/weekly.log 2>&1
+```
+
+systemd timer example (same cadence, same single command):
+
+```ini
+# /etc/systemd/system/backupproof.service
+[Unit]
+Description=Weekly backup restore test
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/backupproof run --config /etc/backupproof.json --report /var/log/backupproof/proof.json
+
+# /etc/systemd/system/backupproof.timer
+[Unit]
+Description=Weekly backupproof run
+[Timer]
+OnCalendar=Sun 03:30
+Persistent=true
+[Install]
+WantedBy=timers.target
+```
+
+## What was live-tested here vs. simulated — read this first
+
+The sandbox has **no `/dev/kvm`, no QEMU, no Proxmox host**.
+Restic and borg were NOT available at v0.1.0 build time — but
+v0.2.0 installed real release binaries (restic 0.17.3, borg
+1.4.1, downloaded from their GitHub releases; `apt` was unusable
+— its update hung on a slow mirror) and ran the real paths live.
+So, honestly:
+
+- **Live-tested here (real code, real execution, covered by the
+  test suite):** backup discovery parsing for restic JSON,
+  borg JSON, and Proxmox vzdump filenames; latest-backup
+  selection; restic/borg/qmrestore/pct command construction;
+  all three smoke packs (real HTTP fetches, real SQLite queries,
+  real file hashing); verdict logic including mixed results;
+  error honesty (no backup, restore failure, boot timeout);
+  exit codes; end-to-end fixture runs (PASS and FAIL); and —
+  **new in v0.2.0 — real restic and real borg end-to-end runs:**
+  a real restic repo and a real borg repo were created, backed
+  up, listed, restored by `RealRunner`, and smoke-checked by the
+  full CLI — both reported `PASS: backup restores, all smoke
+  checks passed (file-level backup — content verified, no VM
+  boot)`, exit 0, with all three packs genuinely passing
+  (web served from the restored tree, real SQLite query, real
+  sha256). The restic/borg real mode is no longer simulated.
+- **Fixture/simulated here, labeled as such everywhere it
+  appears:** the restore+boot layer when run with a `fixture`
+  source. Fixture restore copies a fixture tree; fixture boot is
+  simulated from `boot.json` (it does start a real localhost HTTP
+  server for the webroot, so the web pack is genuinely checked).
+  Every simulated result prints `mode: simulated` and
+  `SIMULATED restore/boot` in text and `"mode": "simulated"` in
+  JSON. A simulated result is never a claim that a real backup
+  restored or booted.
+- **Command-sequence tested, NOT executed against a real host:**
+  the Proxmox flow (pre-flight status, `qmrestore`/`pct restore`,
+  start, probe, stop, destroy) is tested end-to-end against fake
+  `qm`/`qmrestore` binaries that log every invocation — the
+  sequence, the existing-VMID refusal, the missing-VMID refusal,
+  and cleanup-on-failure are all proven, but no real Proxmox host
+  was touched. The old "boot the restored `.qcow2` with QEMU"
+  path was **removed** in v0.2.0: no v0.2.0 flow boots a local
+  disk image (Proxmox boots on the Proxmox host; restic/borg are
+  file-level), and the QEMU helper survives only as a tested
+  utility for a future local-image source.
+
+**What a real host needs for the full path:** restic and/or borg
+installed (passwords via `RESTIC_PASSWORD` / `BORG_PASSPHRASE`
+env), or a Proxmox host with a dump dir + a throwaway VMID.
+If a tool is missing, `run` exits 2 with `MISSING_TOOL` — it
+never reports PASS on an unverified restore.
+
+## What v1 does NOT do (deliberately)
+
+Fleet dashboards, a built scheduler service, team-tier features,
+Windows support, VMware estates, any paid gating, and any smoke
+pack beyond web, DB, and files. The paid team tier (C$19/mo,
+later, not v1) and any fourth pack are out of scope until the owner
+verdicts this pair.

backupproof-0.2.0/README.md

@@ -0,0 +1,316 @@
+# backupproof — we prove your backup weekly
+
+The #1 backup failure is not "no backup" — it's "backup never
+tested, restore fails." backupproof takes the latest restic, borg,
+or Proxmox backup, restores it into a throwaway target, verifies
+it, and reports PASS or FAIL **with proof**: which checks passed,
+which failed, and the evidence for each.
+
+One verdict, three smoke packs only — web, DB, files. Nothing else.
+
+**What "verify" means depends on the source — and the report says
+which (v0.2.0 honesty fix):** restic/borg backups are file-level,
+so the restored *files* are content-checked; there is no disk
+image to boot, and the PASS line says so. Proxmox backups restore
+into a throwaway VMID on the Proxmox host and are probed there
+(web pack via a probe URL). A PASS line never claims a boot that
+did not happen.
+
+## Install (local)
+
+```sh
+pip install .
+# or, for development:
+pip install -e .
+# or without installing, from this directory:
+PYTHONPATH=. python3 -m backupproof --help
+```
+
+Requires Python 3.9+. Stdlib only — no third-party dependencies,
+no keys, no accounts, no telemetry, no phone-home.
+
+## Usage
+
+```sh
+# The verdict: latest backup -> restore -> boot -> smoke -> PASS/FAIL
+backupproof run --config backupproof.json
+backupproof run --config backupproof.json --json --report proof.json
+
+# List backups for a source (newest first)
+backupproof list --config backupproof.json
+backupproof list --source-type restic --repo /srv/backups --json
+
+# Validate a config without restoring or booting anything
+backupproof validate --config backupproof.json
+
+# Write example config + fixture files (runnable: run --config <dir>/config.json)
+backupproof init --output backupproof-examples
+```
+
+Exit codes, CI-usable: **0 = PASS, 1 = FAIL (a check failed),
+2 = ERROR** (no backup found, restore failure, boot failure or
+timeout, bad config, missing tool). `--json` works on all commands.
+
+### Config
+
+A JSON file naming the source and the smoke checks:
+
+```json
+{
+  "source": {"type": "restic", "repo": "/srv/backups"},
+  "checks": {
+    "web": [{"name": "homepage", "path": "/",
+             "expect_status": 200, "expect_contains": "Welcome"}],
+    "db": [{"name": "users table", "db_file": "app.db",
+            "query": "SELECT count(*) FROM users", "expect_rows_min": 1}],
+    "files": [{"name": "config", "path": "etc/app.conf",
+               "sha256": "<hex>", "size_min": 10}]
+  }
+}
+```
+
+Source types: `restic` (`repo`), `borg` (`repo`), `proxmox`
+(`dump_dir` — a vzdump directory), `fixture` (`dir` — see below).
+DB checks run the query against a SQLite file in the restored
+target (stdlib `sqlite3`), or run a `command` (e.g. `psql`) and
+check its output. Web checks fetch a real URL: `path` is resolved
+against the served/restored target's base URL, or give a full `url`.
+Files checks take `path` plus any of `sha256`, `size_min`,
+`size_max`, `size_exact`, and `max_age_days`: the restored file's
+modification time (as preserved by restic/borg) must be within N
+days of the **backup's timestamp**, not of now — catches a nightly
+dump file that stopped updating inside a fresh backup (`FILE_STALE`,
+both dates reported). An unknown backup timestamp is a FAIL, never
+a pass.
+Optional `"mode": "0640"` and `"owner": "postgres"` compare the
+restored file's permission bits and owning user (`pwd`)
+(`FILE_MODE_MISMATCH` / `FILE_OWNER_MISMATCH`). On non-POSIX
+hosts (Windows) both are a FAIL "not verifiable on this OS", never
+a pass. Note: restic and borg restore file ownership only when run
+as root; run as another user, restored files belong to that user.
+
+### Per-source fields
+
+- `restic` / `borg`: `repo` (required). Optional `serve_dir` —
+  a directory inside the restored tree (e.g. `"webroot"`) that
+  backupproof serves over real localhost HTTP, so web checks can
+  hit the *restored* content (labelled "restored content, not a
+  VM" in the report). Without `serve_dir`, web checks need full
+  `url` values. **Passwords pass through the operator's env:**
+  `RESTIC_PASSWORD` for restic, `BORG_PASSPHRASE` for borg —
+  backupproof adds no credential handling of its own.
+- `restic` / `borg` optional `"restore": "checked-paths"`
+  (default `"full"`): restore only the paths the checks read —
+  files-check `path`s, db `db_file`s and `serve_dir` (restic:
+  repeated `--include /<path>`; borg: `extract` with path
+  arguments). The restore line and the PASS line then say
+  `partial (N paths) — only checked paths restored; the rest of
+  the backup was not restore-tested`. A config with no
+  path-bearing check is a `CONFIG_ERROR`. Opt-in only: a partial
+  restore does not prove the whole backup restores.
+- `proxmox`: `dump_dir` (required), `throwaway_vmid` (REQUIRED —
+  backupproof refuses to guess a VMID it will later destroy),
+  `storage` (default `"local"`). The restore runs `qmrestore` /
+  `pct restore` into the throwaway VMID, starts it, probes it
+  (with `--probe-url`), then stops and destroys **only that
+  VMID**. A pre-flight `qm/pct status <vmid>` refuses the run if
+  the VMID already exists. **Pack guard:** db/files packs cannot
+  verify a VM's filesystem from the host, so a Proxmox real-mode
+  config containing them is an ERROR (`PROXMOX_PACK_UNSUPPORTED`,
+  exit 2) naming the packs and the remedy (web checks with
+  `--probe-url`, or run backupproof inside the guest) — packs are
+  never silently dropped and PASSed.
+
+### Repository integrity step (opt-in)
+
+`--integrity` runs `restic check` (add `--read-data-subset PCT`
+to also read that share of the pack data) or `borg check
+--repository-only` (`--verify-data` for `borg check
+--verify-data`) **before** restoring. A failed check is an ERROR
+(`INTEGRITY_FAILED`, exit 2) carrying the tool's last 20 output
+lines; a passed one adds `integrity: {tool, args, ok}` to the
+report. Cost warning: restic's documentation notes that reading
+pack data downloads it from the repository, which is slow and can
+cost money on cloud storage. Plain `restic check` (no subset)
+checks structure only. Use a small subset, not full reads, weekly.
+
+### Dead-man's-switch ping (opt-in)
+
+`--ping-url URL` sends one HTTP GET after the verdict: `URL` on
+PASS, `URL/fail` on FAIL or ERROR — the healthchecks.io
+convention, so a missed weekly run also alerts. 10-second
+timeout. A ping failure prints a warning on stderr and never
+changes the exit code. Nothing is sent unless the flag is given.
+
+### Staleness gate
+
+Top-level `max_age_days` (or `--max-age-days`, CLI wins): when
+the latest backup is older than that, the verdict carries a
+warning. With `--fail-on-stale`, the run refuses outright
+(`STALE_BACKUP`, exit 2) before restoring anything. A backup
+whose timestamp is missing or unparseable warns ("cannot
+determine age") and never fails on staleness alone.
+
+### Which packs verify what, per source
+
+| Source | web pack | db pack | files pack |
+|---|---|---|---|
+| restic / borg (real) | served restored tree (`serve_dir`) or explicit URL | restored files | restored files |
+| proxmox (real) | booted VM via probe URL | **refused** (pack guard) | **refused** (pack guard) |
+| fixture (simulated) | served fixture webroot over real HTTP | fixture tree | fixture tree |
+
+The report's `verified against:` line states this per run, and
+`--report` JSON carries `boot_kind`, `boot_probed`,
+`verified_against`, `warnings`, `restore_partial`, `integrity`
+and `restore_seconds` fields. `restore_seconds` is the wall time
+of the restore step only (not boot or probe) — RTO evidence; the
+text shows `restore: … in 37.2s`. In simulated (fixture) mode it
+times the fixture copy and is labelled `(simulated)`.
+
+A run with no checks configured is an ERROR, never a PASS. A
+check that cannot be verified is a FAIL, never skipped silently.
+
+### Example PASS output
+
+```
+PASS (simulated): backup restores and boots in simulation, all smoke checks passed
+  backup: fixture snap-20261028 (2026-10-28T03:00:00Z)
+  mode: simulated (SIMULATED restore/boot — not a real VM boot)
+  restore: SIMULATED restore into /tmp/backupproof-yoi9_m9l/restored (3 files copied from fixture)
+  boot: SIMULATED boot completed in 42s (fixture boot.json; not a real VM boot); serving webroot webroot at http://127.0.0.1:34147
+  verified against: restored fixture tree (web pack served over real HTTP from the restored webroot)
+  PASS [web] homepage: HTTP 200, body contains 'Welcome'
+  PASS [db] users: query returned 1 row(s): [('alice',)]
+  PASS [files] config: app.conf: 10 bytes, sha256 matches
+```
+
+A real restic/borg run reports instead:
+`PASS: backup restores, all smoke checks passed (file-level backup — content verified, no VM boot)` —
+and a Proxmox run with no probe URL reports
+`PASS: backup restores, VM started (unprobed), all smoke checks passed`.
+
+### Example FAIL output (failing check named)
+
+Change the restored homepage so it no longer contains "Welcome"
+and the same run reports:
+
+```
+FAIL: 1 of 3 smoke check(s) failed
+  backup: fixture snap-20261028 (2026-10-28T03:00:00Z)
+  mode: simulated (SIMULATED restore/boot — not a real VM boot)
+  restore: SIMULATED restore into /tmp/backupproof-y8b2y4d3/restored (3 files copied from fixture)
+  boot: SIMULATED boot completed in 42s (fixture boot.json; not a real VM boot); serving webroot webroot at http://127.0.0.1:45629
+  FAIL [web] homepage (WEB_CONTENT_MISSING): HTTP 200 but body lacks 'Welcome' (first 200 chars: 'Something else entirely\n')
+  PASS [db] users: query returned 1 row(s): [('alice',)]
+  PASS [files] config: app.conf: 10 bytes, sha256 matches
+```
+
+Named failures: web — `WEB_UNREACHABLE`, `WEB_STATUS_MISMATCH`,
+`WEB_CONTENT_MISSING`; DB — `DB_FILE_MISSING`, `DB_QUERY_FAILED`,
+`DB_NO_ROWS`, `DB_CONTENT_MISSING`, `DB_COMMAND_FAILED`; files —
+`FILE_MISSING`, `FILE_SIZE_MISMATCH`, `FILE_HASH_MISMATCH`,
+`FILE_STALE`, `FILE_MODE_MISMATCH`, `FILE_OWNER_MISMATCH`.
+Errors (exit 2): `NO_BACKUP_FOUND`, `RESTORE_FAILED`,
+`BOOT_FAILED`, `BOOT_TIMEOUT`, `MISSING_TOOL`, `CONFIG_ERROR`,
+`INTEGRITY_FAILED`.
+
+### Try it (fixture example, no backup tools needed)
+
+```sh
+backupproof run --config examples/config.json
+```
+
+The example fixture restores a small tree (webroot, `app.conf`,
+SQLite `app.db`) and simulates boot while genuinely serving the
+webroot over real localhost HTTP, so the web check is really
+exercised.
+
+## Weekly cadence (doc example only — no built scheduler)
+
+backupproof has no daemon and no built-in scheduler by design.
+Run it weekly from cron or a systemd timer. Cron example (Sundays
+03:30, proof report kept per run):
+
+```cron
+30 3 * * 0 /usr/local/bin/backupproof run --config /etc/backupproof.json --report /var/log/backupproof/proof-$(date +\%F).json >> /var/log/backupproof/weekly.log 2>&1
+```
+
+systemd timer example (same cadence, same single command):
+
+```ini
+# /etc/systemd/system/backupproof.service
+[Unit]
+Description=Weekly backup restore test
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/backupproof run --config /etc/backupproof.json --report /var/log/backupproof/proof.json
+
+# /etc/systemd/system/backupproof.timer
+[Unit]
+Description=Weekly backupproof run
+[Timer]
+OnCalendar=Sun 03:30
+Persistent=true
+[Install]
+WantedBy=timers.target
+```
+
+## What was live-tested here vs. simulated — read this first
+
+The sandbox has **no `/dev/kvm`, no QEMU, no Proxmox host**.
+Restic and borg were NOT available at v0.1.0 build time — but
+v0.2.0 installed real release binaries (restic 0.17.3, borg
+1.4.1, downloaded from their GitHub releases; `apt` was unusable
+— its update hung on a slow mirror) and ran the real paths live.
+So, honestly:
+
+- **Live-tested here (real code, real execution, covered by the
+  test suite):** backup discovery parsing for restic JSON,
+  borg JSON, and Proxmox vzdump filenames; latest-backup
+  selection; restic/borg/qmrestore/pct command construction;
+  all three smoke packs (real HTTP fetches, real SQLite queries,
+  real file hashing); verdict logic including mixed results;
+  error honesty (no backup, restore failure, boot timeout);
+  exit codes; end-to-end fixture runs (PASS and FAIL); and —
+  **new in v0.2.0 — real restic and real borg end-to-end runs:**
+  a real restic repo and a real borg repo were created, backed
+  up, listed, restored by `RealRunner`, and smoke-checked by the
+  full CLI — both reported `PASS: backup restores, all smoke
+  checks passed (file-level backup — content verified, no VM
+  boot)`, exit 0, with all three packs genuinely passing
+  (web served from the restored tree, real SQLite query, real
+  sha256). The restic/borg real mode is no longer simulated.
+- **Fixture/simulated here, labeled as such everywhere it
+  appears:** the restore+boot layer when run with a `fixture`
+  source. Fixture restore copies a fixture tree; fixture boot is
+  simulated from `boot.json` (it does start a real localhost HTTP
+  server for the webroot, so the web pack is genuinely checked).
+  Every simulated result prints `mode: simulated` and
+  `SIMULATED restore/boot` in text and `"mode": "simulated"` in
+  JSON. A simulated result is never a claim that a real backup
+  restored or booted.
+- **Command-sequence tested, NOT executed against a real host:**
+  the Proxmox flow (pre-flight status, `qmrestore`/`pct restore`,
+  start, probe, stop, destroy) is tested end-to-end against fake
+  `qm`/`qmrestore` binaries that log every invocation — the
+  sequence, the existing-VMID refusal, the missing-VMID refusal,
+  and cleanup-on-failure are all proven, but no real Proxmox host
+  was touched. The old "boot the restored `.qcow2` with QEMU"
+  path was **removed** in v0.2.0: no v0.2.0 flow boots a local
+  disk image (Proxmox boots on the Proxmox host; restic/borg are
+  file-level), and the QEMU helper survives only as a tested
+  utility for a future local-image source.
+
+**What a real host needs for the full path:** restic and/or borg
+installed (passwords via `RESTIC_PASSWORD` / `BORG_PASSPHRASE`
+env), or a Proxmox host with a dump dir + a throwaway VMID.
+If a tool is missing, `run` exits 2 with `MISSING_TOOL` — it
+never reports PASS on an unverified restore.
+
+## What v1 does NOT do (deliberately)
+
+Fleet dashboards, a built scheduler service, team-tier features,
+Windows support, VMware estates, any paid gating, and any smoke
+pack beyond web, DB, and files. The paid team tier (C$19/mo,
+later, not v1) and any fourth pack are out of scope until the owner
+verdicts this pair.