# SYSADMIN CHRONICLES — SNAPSHOT CHAIN
> Version 1.0
>
> This document defines what each named baseline snapshot represents,
> how the snapshot chain is built, and what assumptions quest authors
> can make about VM state at each snapshot.

---

## POLICY

Each `baseline.post-qXXX` snapshot represents the **canonical clean-branch
outcome** of quest QXXX — meaning all prior quests were resolved via their
highest-priority (best) solution branch.

Player state diverges from the baseline during play. The baseline is always
the authored "good state" for that point in the arc, built independently of
any player's actual save.

**A baseline snapshot is never built from a bad or partial branch outcome.**
If a player took the wrong branch, their VM state differs from the baseline
for all subsequent quests. That divergence is intentional and is the game.

---

## SNAPSHOT CHAIN TABLE

| Snapshot Name | VM(s) | Built After | Represents |
|---------------|-------|-------------|------------|
| `baseline.day-one` | workstation | fresh image | Brand new ares workstation. No player account SSH key. Provisioning script ran but authorized_keys absent. |
| `baseline.clean` | web_server | fresh image | Fresh hermes. nginx installed, no config errors, logrotate present, web root owned by www-data. Ready for Q002 to break it. |
| `baseline.clean` | build_machine | fresh image | Fresh vulcan. NTP disabled (for Q006 scenario). Arch base install, pacman configured to use internal repo. |
| `baseline.post-q001` | workstation | Q001 clean branch | Player SSH key in authorized_keys with correct permissions (0600 file, 0700 dir). Used as the implied state for all subsequent quests requiring SSH access. Not an explicit snapshot — workstation just stays live from Q001 onward. |
| `baseline.post-q004` | web_server | Q004 clean branch | hermes with: nginx stable+enabled, logrotate configured, web root owned by www-data recursively. All of Q002–Q004 resolved cleanly. Used as starting state for Q005 and Q007. |
| `baseline.post-q006` | build_machine | Q006 clean branch | vulcan with NTP enabled and healthy, archlinux-keyring refreshed, builds working. Used as starting state for Q008. |

---

## HOW SNAPSHOTS ARE BUILT

Snapshots are produced by `tools/vm/seed-vms.sh` in sequence:

```
1. Build base VM images from cloud-init or preseed
2. Run base configuration (hostname, users, packages, game helpers)
3. Run suppress-maintenance-noise.sh
4. Take baseline.clean snapshot
5. Run Q001-prep.sh → take no snapshot (workstation stays live)
6. Run Q002-prep.sh through Q004-prep.sh sequentially on web_server
7. Apply clean-branch outcome state manually or via a post-quest-state script
8. Take baseline.post-q004 snapshot on web_server
9. Run Q006-prep.sh on build_machine
10. Apply clean-branch outcome state on build_machine
11. Take baseline.post-q006 snapshot on build_machine
```

Step 7 and 10 ("apply clean-branch outcome state") are done via dedicated
scripts in `tools/vm/quest-prep/`:

```
Q004-post-clean.sh   — sets web root ownership, confirms logrotate, enables nginx
Q006-post-clean.sh   — enables systemd-timesyncd, refreshes archlinux-keyring
```

These post-clean scripts are the authoritative definition of what "clean
branch" means for snapshot purposes.

---

## WHAT QUEST AUTHORS CAN ASSUME

When authoring a quest against `baseline.post-q004`, you can assume:
- nginx is active and enabled on hermes
- /etc/logrotate.d/nginx exists and is correct
- /var/www/axiomworks is owned by www-data recursively
- The deploy service runs as www-data and can write to /var/www/axiomworks
- No Q002/Q003/Q004 broken state exists
- Q005 and Q007 both build on this clean hermes state

When authoring a quest against `baseline.post-q006`, you can assume:
- Everything in post-q004 (hermes state)
- systemd-timesyncd is active and enabled on vulcan
- archlinux-keyring is up to date
- pacman -Syu works without signature errors
- Q008 uses this as its clean starting baseline

If your quest needs to break something that was fixed in a prior quest,
your prep script must re-break it after the post-clean baseline is applied.
Document this explicitly in your prep script's header comment.

---

## DEVELOPER RESET

To rebuild all baselines from scratch:

```bash
bash tools/vm/snapshot-all.sh --revert-to baseline.clean
bash tools/vm/seed-vms.sh
```

This is destructive and should only be run during authoring or CI.
It is not available in the shipped game.