# Versioning & Stability

What you can rely on, per surface — the SDK packages, the REST API, and the experimental tier.

## SDK packages: 0.x semver

All packages (`@peltier/core`, `@peltier/react`, `@peltier/react-core`, `@peltier/react-native`, `@peltier/node`) currently ship as **0.x**. Per semver's 0.x rules, **breaking changes land on minor versions** (`0.1.0` → `0.2.0`); patch releases (`0.1.0` → `0.1.1`) are fixes only. Practical guidance:

- Pin with a tilde (`~0.1.0`) or an exact version — a caret (`^0.1.0`) already means "no breaking changes" under npm's 0.x semantics, but be deliberate about it.
- Keep the packages on the **same version** — they are released together, and mixing versions across the `core` / `react-core` / `react` layering is unsupported.
- Read the release notes on every minor bump; breaking changes are called out per package.

## REST API: `/v1` stability promise

The versioned merchant surface (`/v1/*`) is **stable**: existing fields and endpoints are not removed or repurposed within `/v1`. Additive changes — new optional request fields, new response fields, new endpoints — land without notice, so parse responses leniently (ignore unknown fields). The session-scoped browser surface (`/sessions/*`, unversioned) is consumed through the SDK, which is the compatibility layer — drive it via the SDK rather than hand-rolled calls.

## Experimental tier: Lunar

Surfaces marked **`experimental`** — currently the **Lunar** stealth family ([Flow D](/docs/flow-d-stealth-checkout.md), [Flow E](/docs/flow-e-stealth-request.md), the `/stealth/*` endpoints and their SDK helpers) — sit outside both promises above: they **may change or be removed on any release**, including patch releases, and parts are gated pre-mainnet (see the [availability matrix](/docs/availability.md)). Don't build load-bearing production paths on the experimental tier without pinning exact versions and watching the release notes.

## Changelog

Every release is documented in the project's **GitHub Releases** — per-package notes with breaking changes flagged. The docs site always describes the latest release.