# Sanoid Policy Model

Use this file when deciding how aggressive snapshot retention should be.

## Core rule

Sanoid is for retention policy on persistent datasets.

It is not the mechanism that defines whether a runtime resets on every run.
That belongs to the runtime lifecycle:

- persistent service -> Sanoid can help
- golden image -> Sanoid can help lightly
- disposable runner -> use clone, rollback, or destroy logic instead

## Policy classes

### 1. critical-data

Examples:

- `db`

Characteristics:

- persistent
- hardest to recreate
- schema and data matter
- rollback points must survive mistakes and migrations

Recommended policy:

- hourly snapshots
- daily snapshots
- monthly snapshots
- manual milestone snapshots before schema or extension changes

### 2. persistent-service

Examples:

- `controlplane`

Characteristics:

- persistent
- operationally important
- largely rebuildable from code, but rollback is still valuable

Recommended policy:

- moderate hourly retention
- daily retention
- light monthly retention
- manual snapshots before upgrades and risky runtime changes

### 3. rebuildable-service

Examples:

- future `webui`

Characteristics:

- service state matters less than code and config
- usually easier to rebuild than `db`

Recommended policy:

- light retention
- daily snapshots may be enough
- hourly snapshots optional
- manual snapshots before deploys

### 4. personal-workspace

Examples:

- `browser-vm-xfce` used by a real human with logins and browser state

Characteristics:

- persistent
- contains valuable session state
- should not be reset automatically after each run

Recommended policy:

- manual milestone snapshots
- optional light Sanoid retention while actively changing the image
- no automatic reset on run completion

### 5. automation-base

Examples:

- `browser-vm-base-tmux`
- `browser-vm-browser`

Characteristics:

- stable source image
- intended to spawn clones
- changes rarely and deliberately

Recommended policy:

- manual milestone snapshots
- optional light Sanoid retention
- protect the base image, not every derived run

### 6. automation-runner

Examples:

- per-task browser clone
- headless automation instance without personal accounts

Characteristics:

- disposable
- should return to a known clean baseline
- history is not the goal

Recommended policy:

- no regular Sanoid retention
- destroy after run or rollback to base snapshot
- keep only exported artifacts, logs, screenshots, and results

## Recommended starting point

Target these first:

- `zroot/clawdie-runtime/jails/controlplane`
- later: `zroot/clawdie-runtime/jails/db`

Suggested starter policy split:

- `controlplane` -> moderate automated retention
- `db` -> stronger automated retention
- workers -> none
- browser bases -> manual milestone snapshots first

## Manual snapshot naming baseline

Keep manual snapshot names aligned with:

```text
<purpose>-DD-mon-YYYY
```

or, when needed:

```text
<purpose>-DD-mon-YYYY-HH-MM-SS
```

## Why start narrow

The first mistake to avoid is enabling broad recursive snapshot automation across
all datasets.

Different runtime roles need different rollback behavior:

- `db` needs durable rollback points
- `controlplane` needs moderate safety
- `webui` is lighter
- `automation-runner` should reset, not accumulate history
