# `LLMDB.Snapshot`
[🔗](https://github.com/agentjido/llm_db/blob/main/lib/llm_db/snapshot.ex#L1)

Canonical snapshot artifact helpers.

Snapshots are the immutable unit of metadata publication and runtime loading.
They are stored as a single `snapshot.json` file, addressed by `snapshot_id`,
and optionally mirrored to GitHub Releases.

# `integrity_policy`

```elixir
@type integrity_policy() :: :strict | :warn | :off
```

# `build_dir`

```elixir
@spec build_dir() :: String.t()
```

Returns the local build output directory for snapshots.

# `build_meta_path`

```elixir
@spec build_meta_path() :: String.t()
```

Returns the default build artifact path for `snapshot-meta.json`.

# `build_path`

```elixir
@spec build_path() :: String.t()
```

Returns the default build artifact path for `snapshot.json`.

# `counts`

```elixir
@spec counts(map()) :: %{
  provider_count: non_neg_integer(),
  model_count: non_neg_integer()
}
```

Returns provider/model counts for a snapshot document.

# `decode`

```elixir
@spec decode(
  binary(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Decodes, verifies, migrates, and validates a snapshot document from JSON.

The optional `:integrity_policy` controls checksum mismatch handling. A
snapshot ID detects accidental corruption or content mismatch; it does not
authenticate the snapshot publisher.

# `encode`

```elixir
@spec encode(map()) :: String.t()
```

Encodes a snapshot or metadata document as deterministic compact JSON.

Object keys are sorted recursively. Array order and every encoded value are
preserved. Schema v2 documents are normalized to the sparse wire shape before
encoding; schema v1 and non-snapshot metadata documents only lose
insignificant JSON whitespace.

# `from_engine_snapshot`

```elixir
@spec from_engine_snapshot(
  map(),
  keyword()
) :: map()
```

Builds a canonical snapshot document from an engine snapshot.

# `history_archive_filename`

```elixir
@spec history_archive_filename() :: String.t()
```

# `history_meta_filename`

```elixir
@spec history_meta_filename() :: String.t()
```

# `latest_filename`

```elixir
@spec latest_filename() :: String.t()
```

# `metadata`

```elixir
@spec metadata(map(), map()) :: map()
```

Builds snapshot metadata suitable for `snapshot-index.json` and `latest.json`.

# `packaged_path`

```elixir
@spec packaged_path() :: String.t()
```

Returns the packaged snapshot file path.

# `read`

```elixir
@spec read(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Reads, verifies, migrates, and validates a snapshot document from disk.

# `schema_version`

```elixir
@spec schema_version() :: pos_integer()
```

Returns the canonical snapshot schema version.

# `snapshot_filename`

```elixir
@spec snapshot_filename() :: String.t()
```

# `snapshot_id`

```elixir
@spec snapshot_id(map()) :: String.t()
```

Computes the content-addressed snapshot ID for a snapshot document.

# `snapshot_index_filename`

```elixir
@spec snapshot_index_filename() :: String.t()
```

# `snapshot_meta_filename`

```elixir
@spec snapshot_meta_filename() :: String.t()
```

# `source_packaged_path`

```elixir
@spec source_packaged_path() :: String.t()
```

Returns the source-tree packaged snapshot path used for release packaging.

# `sparse_schema_version`

```elixir
@spec sparse_schema_version() :: pos_integer()
```

Returns the opt-in sparse snapshot schema version.

Sparse snapshots are readable in this release, but the packaged and published
default remains schema v1 for backwards compatibility.

# `supported_schema_versions`

```elixir
@spec supported_schema_versions() :: [pos_integer()]
```

Returns every snapshot schema version accepted by the reader.

# `to_sparse`

```elixir
@spec to_sparse(map()) :: map()
```

Converts a canonical v1 snapshot to the deterministic sparse v2 wire shape.

Only schema-known provider/model nulls and defaults are omitted. Unknown keys,
nested `extra` data, explicit values, and array order are preserved. The
content-addressed snapshot ID is recalculated for the v2 representation.

# `verify`

```elixir
@spec verify(map()) :: :ok | {:error, term()}
```

Verifies snapshot checksum consistency and document safety.

Snapshot IDs detect corruption or mismatched content. They are not an
authenticity or trust guarantee.

# `write!`

```elixir
@spec write!(String.t(), map()) :: :ok
```

Writes a snapshot or metadata document to disk.

---

*Consult [api-reference.md](api-reference.md) for complete listing*