---
title: "Program Versioning"
description: "How Arete gives every program release a version number you can reason about, and why nobody picks it by hand."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

> For the complete documentation index optimized for AI agents, see [llms.txt](https://docs.arete.run/llms.txt) or [llms-full.txt](https://docs.arete.run/llms-full.txt). A markdown version of this page is available at [/concepts/program-versioning.md](https://docs.arete.run/concepts/program-versioning.md) or by sending `Accept: text/markdown`.
Every program package in the Arete registry has an **Arete version**, such as
`1.2.3`. This version tracks the compatibility of the exact program integration
that Arete publishes: its normalized interface, generated SDK surface, and
hosted Program Release.

The Arete version is separate from any versioning system used by the original
protocol.

If you have met semantic versioning before, the numbers mean what you expect. A
major bump can break existing code, a minor bump adds things, and a patch keeps
the program's contract the same. The unusual part is that no person chooses the
number. Arete works it out by comparing the new release with the last one.

## Why Arete has its own versions

A Solana program address can stay the same while its executable changes. IDLs
and SDK helpers can also change independently. A program address alone
therefore cannot identify the interface and implementation an application was
built against.

Arete records exact identities at each layer:

| Identity             | What it fixes                                                               |
| -------------------- | --------------------------------------------------------------------------- |
| Program ID           | The on-chain address                                                        |
| Normalized IDL hash  | The canonical callable and decodable interface                              |
| `ProgramSpec` hash   | The exact portable program definition                                       |
| Program Release hash | The ProgramSpec, IDL, decoder, and observed on-chain executable identity    |
| Package Release hash | The installable package, including its SDK targets and generated extensions |

These content addresses (hashes of the content itself) are what make a build
exactly reproducible. The Arete semantic version sits on top of that immutable
history as the part people can read: a quick signal of whether an update is safe
to take.

## How a version is produced

The catalog publication pipeline derives versions from artifacts and recorded
history:

```text
canonical IDL + SDK surface
            │
            ▼
 content-addressed program definition
            │
            ▼
structural diff against the last sealed version
            │
            ├── Arete semantic version
            └── generated release notes
                        │
                        ▼
          immutable catalog package
                        │
                        ▼
     exact resolution in arete.lock
```

When a new hosted Program Release is required, the platform also captures the
finalized on-chain executable. Its identity includes the Solana network, loader
kind, and executable payload hash. Arete verifies that the finalized snapshot
stays stable while the release is prepared and refuses publication if it
drifts. The resulting Program Release permanently binds that executable
identity to the exact ProgramSpec and IDL.

No maintainer chooses a bump in a commit message or edits a version to describe
the change. CI compares the proposed package with the last version recorded in
published catalog history, classifies the structural difference, and derives
the next version. Once a version is published, it is never rebound to different
content.

## Version rules

| Classification | Version effect | Meaning                                                                 |
| -------------- | -------------- | ----------------------------------------------------------------------- |
| Unchanged      | No new version | The exact package identity is already published                         |
| Rebuild        | Patch          | The package changed without changing the callable or decodable contract |
| Additive       | Minor          | The contract gained compatible declarations or output fields            |
| Breaking       | Major          | Existing callers or decoders may no longer be compatible                |

A patch can cover an implementation rebuild, an SDK extension change, a new
SDK target, or another packaging change that preserves the program contract. A
minor release can add a new instruction, account type, event, error, or
compatible trailing output field.

Removals, renames, reordering, and type changes are breaking. Adding a required
instruction account or argument is also breaking because every existing caller
must supply or encode it. The classifier works from the normalized structure,
not from source-code text or an IDL's own metadata version.

## Generated release notes

The release notes come from the same structural comparison that decides the
version. They record:

- the classification (`rebuild`, `additive`, or `breaking`);
- the previous Arete version;
- the identities or SDK surfaces that caused the release; and
- a machine-readable contract diff with the affected path and compatibility
  effect.

Because the notes and the version come from the same comparison, the changelog
always matches the version decision. Nothing depends on someone remembering to
write a complete summary.

Inspect the current version, identities, and release notes with:

```bash
a4 explore catalog program <slug> --json
```

The descriptor is the source of truth for what is currently available. Use
`a4 install` to save a version requirement in `arete.toml`; use `a4 update` to
advance within that requirement. Commit `arete.lock` to preserve the exact
package and artifact identities selected for the project.

## Next steps

- [Install and use a Program SDK](/using-programs/overview/)
- [Manage version requirements and lockfiles](/building-stacks/configuration/)
- [Understand programs, views, and stacks](/concepts/programs-views-stacks/)