# Versioning & Integrity

Context Nest provides a tamper-evident version history for every document, with cryptographic hash chains and vault-level checkpoints.

## Key concepts

- **Version history** — Every publish creates a version entry in `history.yaml` with a content hash and a chain hash.
- **Keyframes + change logs** — Full snapshots (keyframes, `vN.md`) at regular intervals, with each intermediate version stored as a **unified-diff change log** (see [Storage Model](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/storage-model) for exactly where the diffs live).
- **Checkpoints** — Vault-level atomic snapshots (like git commits) that pin document versions together. A batch / bulk import seals a **single** checkpoint for the whole batch, not one per document.
- **Hash chains** — SHA-256 chains binding each version to its predecessor, making tampering detectable.
- **Graft-proof numbering** — Numbering is fixed at the source and re-anchored by the repair path, so a document cannot be renumbered or grafted onto a different history by editing its `version` field.

## Versions start at 1

`ctx add` creates **version 1** for a new node (previously the first publish produced version 2). The first recorded version of any node is `1`.

## Lazy chain reads

Reads and writes **no longer replay the entire version chain**. The engine reads the nearest keyframe and applies only the change logs it needs, so operations scale with the work at hand rather than with total history depth. See [Checkpoints](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/checkpoints) and [Storage Model](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/storage-model).

## CLI commands

```bash
ctx history nodes/architecture        # Show version history
ctx reconstruct nodes/architecture 3  # Reconstruct version 3
ctx verify                            # Verify all hash chains
ctx checkpoint list                   # List checkpoints
ctx checkpoint rebuild                # Rebuild checkpoint history
```

See [Integrity Verification](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/integrity-verification) for how tamper, torn seals, and rebuild-laundering are detected.