Versioning & Compatibility

Bardiel will evolve over time: new policies, better scoring, deeper integrations. To keep builders safe, we treat 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 and token genesis, early testnet use

• v0.2.0 – more mature validation engine and policy behavior

• v0.5.0 – Bardiel widely used as Virtual’s default trust oracle

• v1.0.0 – arbitration + trajectory checks, mainnet-ready

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, …) 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, 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": { ... },
  "policy": "safe",
  "version": {
    "target": "v0.5",
    "fallback": "compatible"
  }
}

Possible semantics:

• target: preferred major/minor version range

• fallback: "compatible" or "fail" 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 for the 2026 timeframe:

• v0.x (testnet / early mainnet)

  • APIs and behavior may evolve.

  • Changes will be documented, but some integrations may need adjustments.

  • Best suited for early adopters and close collaborators.

• v1.0+ (mainnet focus)

  • Schemas and semantics are stable enough for production ACP markets.

  • Changes are incremental and additive where possible.

  • Deprecations follow clear timelines and communication.

---

Deprecation Policy (Draft)

When we need to deprecate fields or behaviors, we aim 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, 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 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

• When possible, handle unknown fields in responses gracefully, so Bardiel can add new evidence signals without breaking your integration.

---

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 you can build on it with confidence.