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

Returns the local build output directory for snapshots.

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

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

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

Returns the default build artifact path for snapshot.json.

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

Returns provider/model counts for a snapshot document.

@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.

@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.

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

Builds a canonical snapshot document from an engine snapshot.

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

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

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

Returns the packaged snapshot file path.

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

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

@spec schema_version() :: pos_integer()

Returns the canonical snapshot schema version.

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

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

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

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

@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.

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

Returns every snapshot schema version accepted by the reader.

@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.

@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.

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

Writes a snapshot or metadata document to disk.