> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Snapshotting
> How Roboticks freezes the requirement set per release into an immutable snapshot, what happens when you edit a snapshotted requirement, and how the audit trail works.
# Snapshotting
The single property that makes Roboticks audit-grade is this: when you cut a release, the requirement set for that release is **frozen**. Three years later, when an auditor opens the evidence pack, they see exactly what you verified against — not a drifted-since version, not "what the team meant to verify". The snapshot is the truth.
**A snapshot is immutable.** Edits after a snapshot create a new version of the requirement. The snapshot keeps pointing at the version that existed at snapshot time, forever.
## When a snapshot is created
A snapshot is created when:
| Trigger | What is snapshotted |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| You cut a release in Roboticks (`rbtk release create v1.2.0` or the dashboard equivalent) | The current state of every requirement, every link, and every verification result on the chosen SHA. |
| A scheduled rollup runs (optional, per-project, default off) | Same as above, on a fixed cadence. Useful for monthly audit-ready packs without an explicit release. |
| The SDK calls `client.snapshots.create(...)` from a custom script | Same. |
There is **no automatic snapshot on every push**. Snapshots are deliberate, named events that produce an [evidence pack](/evidence/generation).
## What goes into a snapshot
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart TD
S["Snapshot v1.2.0"] --> R["Requirements at SHA
(immutable copies)"]
S --> L["RequirementLinks at SHA
(@confirms decoder output)"]
S --> T["TestCases at SHA"]
S --> V["Verification results at SHA
(pass/fail per test)"]
S --> A["Audit trail entry
(who, when, why)"]
S --> E["Evidence pack pointer"]
```
Every artifact carries the snapshot ID. Browsing the matrix in "snapshot v1.2.0" mode shows you the world as it was at snapshot time, not the live state.
## Editing a snapshotted requirement
You can edit any requirement at any time. What happens to a snapshotted one:
1. The edit creates a **new version** of the requirement. The version number increments (e.g. `REQ-014@v3` → `REQ-014@v4`).
2. The snapshot keeps pointing at the old version. `v1.2.0` still verifies against `REQ-014@v3`.
3. The live state moves to `REQ-014@v4`. The next snapshot will pick up `v4`.
4. The audit trail records the diff (field-level), the author, the timestamp, and the linked release(s) affected.
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
V3["REQ-014@v3
'within 100 ms'"] --> SN1["Snapshot v1.2.0"]
V3 -- "Edit: 'within 80 ms'" --> V4["REQ-014@v4"]
V4 --> Live["Live state"]
V4 --> SN2["Snapshot v1.3.0
(future)"]
```
This is how Roboticks reconciles two things auditors care about:
* **Stability.** A release once shipped does not change.
* **Evolution.** Requirements get tightened, clarified, and added as the product matures.
## Deleting a snapshotted requirement
You can't truly delete a snapshotted requirement — the snapshot needs it. What you can do:
* **Mark as obsolete** in the live state. Future snapshots won't include it. Past snapshots still do.
* **Hard-delete from the live state.** Permitted only if the requirement is not in any snapshot. Once snapshotted, it's around for the snapshot's retention life.
## Snapshot retention
| Tier | Snapshot retention |
| ---------- | ------------------------------------------------------ |
| Free | 90 days |
| Team | 10 years (EU Product Liability tail) |
| Enterprise | 10 years (Glacier Deep Archive, retrievable on demand) |
The evidence pack PDF / ReqIF / ZIP for each snapshot is tamper-evident — every file's SHA-256 is chained into the next, and the chain head is signed. See [Evidence pack](/evidence/generation).
## The audit trail
Every edit on a requirement — pre- or post-snapshot — is appended to the requirement's audit trail. Each entry records:
* The full pre/post state of every field that changed.
* The author (GitHub user or Roboticks dashboard user).
* The timestamp (server-side UTC).
* The originating action (web edit, ReqIF re-import, SDK call, etc.).
* The releases affected (which snapshots reference the prior version).
The audit trail is **append-only**. It is exported with the evidence pack and signed in the same hash chain. Auditors expect this; we make it the default.
```json theme={null}
{
"requirement_id": "REQ-014",
"version_from": 3,
"version_to": 4,
"author": "alice@acme.io",
"ts": "2026-05-14T09:12:33Z",
"action": "web_edit",
"diff": [
{"field": "text", "from": "...within 100 ms...", "to": "...within 80 ms..."},
{"field": "title", "from": "...100 ms", "to": "...80 ms"}
],
"snapshots_affected": ["v1.2.0"]
}
```
## Snapshots vs Git tags
A Roboticks snapshot is not a Git tag. They overlap — a snapshot is usually tied to a SHA that is also tagged in Git — but the snapshot captures more than the commit:
| | Git tag | Roboticks snapshot |
| ------------------------------------ | ------------ | -------------------------------------- |
| Source code state | ✓ | ✓ (via SHA pointer) |
| Test results | ✗ | ✓ |
| Requirement set | ✗ | ✓ (frozen) |
| Verification status per requirement | ✗ | ✓ |
| Audit trail of who changed what when | ✗ | ✓ |
| Tamper-evident hash chain | ✗ | ✓ |
| Retention policy | Repo-managed | Tier-bound, 10 yr on Team / Enterprise |
You can cross-reference: a Git tag has an associated snapshot ID; a snapshot points at the SHA + tag.
## Branching: long-lived release branches
Long-lived release branches (e.g. `release/v1.x`) generate their own snapshot lineage. The snapshot for `v1.2.0` is independent of `v1.3.0`, which is independent of `v2.0.0`. Each lineage has its own audit trail and its own evidence packs.
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
M["main"] -- "Snapshot v2.0.0" --> S2["v2.0.0"]
R["release/v1.x"] -- "Snapshot v1.2.0" --> S1a["v1.2.0"]
R -- "Snapshot v1.3.0" --> S1b["v1.3.0"]
```
This matches the way regulated teams ship — `v1.x` keeps getting safety patches for years after `v2.0` lands; each `v1.x.y` patch needs its own audit-grade evidence pack against the requirements as they stood for that lineage.
## Re-running tests against an old snapshot
Sometimes you need to re-run the tests as they existed at a snapshot — for example, to investigate a regression report from the field. The CLI:
```bash theme={null}
rbtk snapshots replay v1.2.0
```
This dispatches a fresh test run on a runner using the SHA from the snapshot, the same runner image tag, and the same test command. Results are written to a **re-verification** record on the snapshot — the original results stay untouched.
## Next
The PDF / ReqIF / ZIP a snapshot generates.
How tree shape interacts with snapshots.
Snapshot vs live coverage states.
`rbtk release` and `rbtk snapshots`.