# Versions and trust tiers

Source: https://opvs.ai/docs/guides/vendors/versions-and-tiers

> Semver rules, immutable versions, peer pins, trust tiers, and how workspaces receive your new versions.

The registry keeps every version you publish. A published `(vendor, name, version)` **never changes**: to change anything, publish a new version.

## Semver

`version` must be real semver: `0.1.0`, not `0.1` or `v1`.

Bump

When

Example

**Major** `1.x → 2.0.0`

breaking: a removed or renamed method, a changed reply shape, a new required input, a changed required entitlement or credential

dropping a tool agents rely on

**Minor** `1.2 → 1.3.0`

additive: a new method, a new optional input, better guidance

adding `searchLeads`

**Patch** `1.2.3 → 1.2.4`

a fix, docs, no change to the surface

correcting a wrong default

Even a typo fix needs a new version. What counts as breaking is covered in [Breaking changes and deprecation](https://opvs.ai/docs/guides/vendors/breaking-changes.md).

## How workspaces receive new versions

Each install records a **pin**, npm-style. The default is `latest`.

Pin

The workspace moves to

`latest` (default)

your newest version

`^1.0.0`

the newest `1.x`

`~1.2.0`

the newest `1.2.x`

`1.2.3`

nothing; it stays on that exact version

OPVS runs the update **once a day (03:00 UTC)** and when its API restarts. Each install moves to the newest version its pin allows. So:

- **Publishing is delivering.** Every `latest` install receives your new version within about a day, with no action from you or the workspace. Release only what you would ship to everyone.
- **A workspace that pinned an exact version stays put** until it changes its pin, unless you flag a [required upgrade](https://opvs.ai/docs/guides/vendors/required-upgrades.md).
- **New required permissions wait for consent.** If a voluntary update needs an entitlement the workspace has not granted, that install is held until a workspace admin agrees.

## Peer pins

If your package declares a peer, its `range` uses the same forms:

```yaml
peer_dependencies:
  - name: "@opvs-ai/opvs-foundation"
    range: "^1.0.0"
```

`^` is the usual choice: the peer's minor and patch releases reach you without a republish. When a peer ships a new **major**, test against it and publish a new version of your package with the range moved (`^2.0.0`).

## Trust tiers

`tier` is a field **you set** in each version's manifest. The registry never changes it, and there is no promotion step.

Tier

Today

`beta` (default)

visible in the marketplace and installable at once. Almost every live package is `beta`.

`internal`

hidden from browsing; a test tier for trying a version before it is public

`community`

reserved for a later phase

`verified`

reserved for a later phase: human-reviewed, full docs, stable usage

Tier is per version. To make a hidden version public, publish a **new** version with `tier: beta`; you cannot change a published one.

Note on rate limits: on `internal`, a method with no rate limit **blocks** the publish; on `beta` it is a warning. See [Security review](https://opvs.ai/docs/guides/vendors/security-review.md).

The badge a workspace sees is the version's tier plus its [security score](https://opvs.ai/docs/guides/vendors/security-review.md#the-score).

## Deprecating a version

There is no soft "deprecated" flag today. A version is `published` or `revoked`. To retire a harmless old version, publish the new one and say so in your changelog; see [Breaking changes and deprecation](https://opvs.ai/docs/guides/vendors/breaking-changes.md#deprecating-without-breaking).

## See any package's history

```bash
curl -s "https://market.opvs.ai/api/v1/registry/packages/@opvs-ai/agentboard/versions" \
  | python3 -c "import sys,json; [print(v['version'], v['tier'], v['status']) for v in json.load(sys.stdin)['versions']]"
```

## Next

[Required upgrades](https://opvs.ai/docs/guides/vendors/required-upgrades.md).