# Nest Checkpoints

A **nest checkpoint** is an atomic, immutable snapshot of the entire vault — the Context Nest equivalent of a git commit.

## Why checkpoints?

Per-document versioning alone cannot guarantee cross-link consistency. When Document B is re-published, any document linking to it immediately resolves to the new version. Checkpoints pin the entire graph at a point in time.

## Structure

Checkpoints are stored in `.versions/context_history.yaml`:

```yaml
checkpoints:
  - checkpoint: 1
    at: "2026-01-15T10:00:00Z"
    triggered_by: "nodes/architecture"
    document_versions:
      nodes/architecture: 1
      nodes/api-reference: 1
    document_chain_hashes:
      nodes/architecture: "sha256:a1b2c3..."
      nodes/api-reference: "sha256:d4e5f6..."
    checkpoint_hash: "sha256:x7y8z9..."
```

## Automatic creation

A new checkpoint is created every time a document is published. The checkpoint records the current version of every published document.

## Batch / bulk import: single seal

A batch or bulk import seals **one** checkpoint for the entire batch — not one checkpoint per imported document. All documents imported in the batch are pinned together at that single checkpoint.

*Confirmed in source: publishing per chunk "would seal a checkpoint per chunk, and every checkpoint re-scans the whole vault (the O(N²) shape this import exists to avoid)," so a bulk import "publishes the lot under a single checkpoint."*

## Lazy chain reads

Resolving a document at a checkpoint does not replay the whole version chain. The engine locates the nearest keyframe and applies only the change logs required to reach the pinned version, so checkpoint resolution scales with the distance to a keyframe rather than with total history depth.

## Pinned resolution

Use `@N` in URIs to resolve documents at a specific checkpoint:

```
contextnest://nodes/architecture@5
```

This returns the version of architecture that was current at checkpoint 5.

## Checkpoint-chain integrity

The checkpoint chain is hardened against several failure and attack modes:

- **Torn seals** — a checkpoint that was partially written (a crash or interrupted seal) is detected rather than trusted.
- **Tamper** — modifying a checkpoint or a recorded document chain hash breaks the checkpoint hash and is caught by `ctx verify`.
- **Races** — concurrent publishes/imports cannot silently produce an inconsistent or overwritten checkpoint.
- **Rebuild-laundering** — a rebuilt checkpoint history cannot be used to "launder" tampered content into a clean-looking chain; the rebuild is validated against the recorded per-document histories.

See [Integrity Verification](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/integrity-verification) for detection details.

## Rebuild

If checkpoint history is corrupted or missing, rebuild it from the per-document histories:

```bash
ctx checkpoint rebuild
```

Rebuild is validated against recorded history and cannot be used to launder tampered content into an apparently valid chain.