> For the complete documentation index, see [llms.txt](https://docs.bardiel.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bardiel.tech/technical-architecture/versioning-and-compatibility.md).

# Versioning & Compatibility

## Versioning & Compatibility

Bardiel will evolve over time: new policies, better scoring, deeper integrations, and tighter alignment with **Base, Virtual, ERC-8004, other onchain agent ecosystems, and Cortensor**.

To keep builders safe, Bardiel treats **versioning** as a first-class concern.

This page explains how Bardiel versions are structured, what is considered “breaking”, and how integrators should think about compatibility.

***

### Versioning Scheme

Bardiel uses a semantic-style version:

`v<major>.<minor>.<patch>`

Examples (illustrative, not final release tags):

* `v0.1.0` – initial spec, early testnet use
* `v0.2.0` – more mature validation engine and policy behavior
* `v0.5.0` – Bardiel widely used as a trust and execution layer across supported ecosystems
* `v1.0.0` – arbitration + trajectory checks, mainnet-focused

#### Interpretation

* **Major** (`1.x.y`)\
  May introduce breaking changes to:
  * status semantics
  * policy behavior guarantees
  * required fields in request / response schemas
* **Minor** (`0.2.x`, `0.5.x`)\
  Adds features or improves internals while keeping:
  * existing schemas valid
  * existing policy names meaningful
* **Patch** (`0.2.1`, `0.2.2`, etc.)\
  Bug fixes, minor tuning, and non-breaking improvements.

***

### Backward Compatibility Guarantees

Within a given **major** version:

* The core request / response envelope:
  * `mode`, `task`, `policy`
  * `status`, `result`, `confidence`, `evidence`, `retry_instructions`
  * `trace_id`, `bardiel_version` will remain valid and interpretable.
* Policy names (`fast`, `safe`, `oracle`, `adaptive`) will keep their **intent**:
  * `fast` remains the cheapest / lowest-effort tier
  * `safe` remains the default for most high-trust workloads
  * `oracle` remains the highest-robustness tier
  * `adaptive` remains the dynamic “start cheap, escalate when needed” tier

Internals (exact miner counts, PoI thresholds, scoring weights, routing heuristics, etc.) may change as Bardiel learns from real traffic, but those changes will not **invert** the meaning of the tiers.

Breaking changes will only be introduced with:

* a **major** version bump (for example `0.x` → `1.0`), or
* clearly marked preview / experimental flags

***

### `bardiel_version` Field

Every Bardiel response includes a `bardiel_version` field, for example:

```
{
  "status": "VALID",
  "result": { "summary": "..." },
  "confidence": 0.91,
  "evidence": { "redundancy": 3 },
  "retry_instructions": null,
  "trace_id": "bardiel-trace-123",
  "bardiel_version": "v0.2.0"
}
```

Integrations should:

* log `bardiel_version` alongside `trace_id`
* use it for debugging and support
* optionally gate advanced features based on minimum version

For example:

> Only use arbitration features if `bardiel_version >= v0.2.0`.

***

### Future Version Negotiation (Draft)

In the future, Bardiel may support **explicit version negotiation**, where callers can express a preference.

Example (conceptual, not finalized):

```
{
  "mode": "delegation",
  "task": { "...task payload..." },
  "policy": "safe",
  "version": {
    "target": "v0.5",
    "fallback": "compatible"
  }
}
```

Possible semantics:

* `target`\
  preferred major / minor version range
* `fallback`
  * `"compatible"` – accept any backward-compatible version
  * `"fail"` – reject the request if the requested range is not available

This design is still a draft and will be documented separately once implemented.\
For now, version exposure is one-way:

* Bardiel → caller via `bardiel_version`

***

### Upgrade Expectations by Phase

High-level expectations:

* **v0.x (testnet / early production)**
  * APIs and behavior may evolve faster
  * changes will be documented, but some integrations may need adjustments
  * best suited for early adopters and close collaborators
* **v1.0+ (mainnet / broader ecosystem focus)**
  * schemas and semantics are stable enough for production integrations across Base, Virtual, ERC-8004, and other ecosystems
  * changes are incremental and additive where possible
  * deprecations follow clear timelines and communication

***

### Deprecation Policy (Draft)

When Bardiel needs to deprecate fields or behaviors, the goal is to:

1. **Introduce alternatives first**\
   Add new fields or behaviors without removing existing ones.
2. **Mark deprecated elements clearly**
   * in documentation
   * optionally in responses (for example, through a `warnings` array)
3. **Allow a grace period**
   * keep deprecated behavior working for a defined window
   * communicate expected removal versions in advance

Exact timelines (for example, “deprecated in v1.1, removed in v2.0”) will be published alongside roadmap updates.

***

### How Builders Can Stay Safe

Practical recommendations:

* always log `bardiel_version` and `trace_id`
* avoid hard-coding assumptions about:
  * exact miner counts per policy
  * internal PoI / PoUW thresholds
  * specific `evidence` sub-fields always being present
* treat the following as stable within a major version:
  * high-level schema (envelope fields)
  * status values and their basic meaning
  * policy names and their relative trust / cost ordering
* handle **unknown fields** in responses gracefully, so Bardiel can add new evidence signals without breaking integrations

This applies whether you are integrating from:

* a Base-native app
* Virtual GAME or ACP
* an ERC-8004-compatible registry or market
* another onchain agent ecosystem

***

### In Short

Bardiel will get smarter and more capable over time, but the **shape** and **meaning** of its public interface will remain predictable within a major version, so builders across **Base, Virtual, ERC-8004, and other onchain agent ecosystems** can integrate with confidence.