# Snapshots (/concepts/snapshots)



A **snapshot** is the compiled, ordered logical state for a [branch](/concepts/branches) head at one moment. It is the bridge between mutable, growing session history and a single, fixed generation: a response pins exactly one snapshot, and that snapshot can be replayed forever.

```json
{
  "id": "snp_01jy...",
  "object": "snapshot",
  "session_id": "ses_01jy...",
  "branch_id": "br_01jy...",
  "branch_version": 17,
  "prompt_compiler_revision": "pc_11",
  "ordered_block_manifest": ["blk_1", "blk_2", "blk_3"],
  "created_at": "2026-06-09T20:15:00Z"
}
```

## What a snapshot pins [#what-a-snapshot-pins]

Compiling a snapshot resolves "the current state of this branch" into a concrete, ordered list of logical blocks. It pins:

* **the branch and its exact version** (`branch_id` + `branch_version`), so the snapshot is tied to a specific point in history;
* **the ordered block manifest**, the sequence of logical blocks the model will see, derived from the session's [bundles](/concepts/bundles) and the branch's [events](/concepts/sessions) in their semantic order;
* **the prompt-compiler revision**, so the rules that turned logical state into ordered blocks are recorded.

## Snapshots live at Layer 1 [#snapshots-live-at-layer-1]

A snapshot is purely **logical** identity. It says nothing about tokenizers, engines, or GPUs. That is the point: the same snapshot can be materialized differently on different runtimes without changing what it is.

<Note>
  The snapshot ID is the anchor of the [materialization key](/concepts/identity-model). Materialization adds tokenizer, chat-template, and serialization revisions on top of the snapshot; KV-realization compatibility adds the physical runtime on top of that. The snapshot itself stays clean of all of it.
</Note>

## Why pinning enables reproducibility [#why-pinning-enables-reproducibility]

Because a snapshot is immutable and fully specified, a [response](/concepts/model-aliases) that pins one snapshot and one [model-alias release](/concepts/model-aliases) is reproducible. Replay can recompile the identical ordered blocks and resolve the identical model target, then compare a candidate execution against the baseline without any drift sneaking in from changed history or shifted routing.

<Steps>
  <Step title="Branch advances to version 17">
    Events have been appended; the head is `evt_017`.
  </Step>

  <Step title="Generate compiles a snapshot">
    The platform pins `branch_version: 17`, the ordered block manifest, and the compiler revision into `snp_...`.
  </Step>

  <Step title="The response binds the snapshot and an alias release">
    From here the logical input is fixed. Re-running the snapshot under the same alias release reproduces the routing decision.
  </Step>
</Steps>

<Warning>
  A snapshot does not pin a model. It pins logical input. The model comes from the [alias release](/concepts/model-aliases) the response binds. Keeping these two separate is what lets you replay the same input against different candidate models.
</Warning>

<CardGroup cols="2">
  <Card title="Identity model" icon="diagram-project" href="/concepts/identity-model">
    Where snapshots sit among the three layers.
  </Card>

  <Card title="Snapshots and reproducibility" icon="rotate" href="/guides/snapshots-and-reproducibility">
    Pin state for faithful replay.
  </Card>
</CardGroup>