Versioning and Capability Governance

This page summarizes the canonical governance model for BDL versioning, compatibility, and capability claims.

The detailed governance records are maintained in the project governance sources. This public page is the human-readable reference for their core rules.

Version domains

BDL uses independent version domains.

The version of one domain must not be treated as the version of another domain.

Domain	Current governed baseline
BDL language / knowledge model	5.2.2
Native Barsa contract	2.0.0
Runtime / Troubleshooting	2.0.0
BDL Authoring surface	No independent current baseline frozen
Documentation site	v1.1.0
Source registry	1.0

Matching version numbers across domains do not imply compatibility.

BDL version model

BDL language versions use:

MAJOR.MINOR.PATCH

• MAJOR — breaking semantic changes.
• MINOR — backward-compatible semantic expansion.
• PATCH — compatible corrections or clarifications that do not materially change the language contract.

Published governed BDL versions are immutable. A semantic change requires a new version.

The current governed BDL baseline is 5.2.2.

Compatibility is directional

Compatibility claims must identify:

• subject;
• target;
• direction;
• scope;
• result;
• evidence;
• provenance.

Backward compatibility evaluates a newer subject against an older target.

Forward compatibility evaluates an older subject against a newer target.

Bidirectional compatibility may be claimed only when both directions have independently been demonstrated for the same scope.

Version numbers alone do not prove compatibility.

Compatibility states

Canonical compatibility states are:

• compatible
• conditionally_compatible
• incompatible
• unknown
• unverified
• not_applicable

unknown must be used when authoritative evidence is insufficient.

Breaking and non-breaking changes

Canonical change classes are:

• breaking
• non_breaking
• conditionally_breaking
• documentation_only
• unknown

A change is breaking when previously valid governed use becomes invalid, governed meaning changes incompatibly, required capability is removed, or previously supported interaction fails within the declared scope.

An additive change is not automatically compatible. Its actual compatibility impact must still be evaluated.

Deprecation and withdrawal

Deprecation and withdrawal are different lifecycle states.

• Deprecated — the item remains recognized or available, but new use is discouraged.
• Withdrawn — the item is no longer approved for current use in the declared scope.

Deprecated, superseded, withdrawn, and historical evidence must not be silently deleted.

Lifecycle transitions must be explicit and auditable.

The four capability layers

Every governed capability claim must identify one of these four layers:

1. Native Barsa

Whether the capability exists natively in Barsa or its authoritative native contract.

Machine-readable identifier: native_barsa

2. Runtime Support

Whether the capability is actually supported in execution or runtime behavior.

Machine-readable identifier: runtime_support

3. BDL Expressibility

Whether the governed BDL language model can represent the capability.

Machine-readable identifier: bdl_expressibility

4. BDL Authoring Availability

Whether the capability can be created, edited, selected, or configured through the applicable BDL authoring surface.

Machine-readable identifier: bdl_authoring

Capability layers must remain independent

A positive result in one layer does not automatically create a positive result in another.

For example, a capability can be:

Native Barsa:               available
Runtime Support:            available
BDL Expressibility:         available
BDL Authoring Availability: unavailable

This is a valid capability profile.

It must not be collapsed into a generic statement such as supported.

Capability states

Canonical capability states are:

• available
• partially_available
• conditionally_available
• unavailable
• unknown
• unverified
• not_applicable
• deprecated
• withdrawn

Capability state and compatibility state are separate dimensions.

For example:

• Capability: available
• Compatibility: compatible

These statements answer different questions.

Evidence requirements

Capability evidence must match the capability layer.

• Native Barsa claims require authoritative native evidence.
• Runtime Support claims require runtime-appropriate evidence.
• BDL Expressibility claims require BDL language/schema/semantic evidence.
• BDL Authoring Availability claims require authoring-surface evidence.

Absence of evidence does not prove unavailable.

When evidence is insufficient, use unknown or unverified.

No cross-layer inference

The following assumptions are not allowed without separate evidence:

• Native Barsa → Runtime Support
• Runtime Support → Native Barsa
• BDL Expressibility → Runtime Support
• Runtime Support → BDL Expressibility
• BDL Expressibility → BDL Authoring Availability
• BDL Authoring Availability → BDL Expressibility

Cross-layer differences are not automatically conflicts

Different results across different capability layers can all be correct.

A real conflict exists only when competing claims address the same capability, layer, version or baseline, scope, and conditions but produce incompatible conclusions.

Within the same layer and compatible scope, Source Precedence and Conflict Resolution rules apply.

No capability layer has blanket precedence over another capability layer.

Machine-readable governance

The project maintains machine-readable capability governance in:

capability-governance.json

It defines:

• the four capability-layer identifiers;
• canonical capability states;
• canonical compatibility states;
• change classes;
• conflict states;
• version domains;
• mandatory governance rules.

The governance data is validated by the project validation workflow.

Relationship to Source of Truth

All version, compatibility, and capability claims remain subject to the BDL Source of Truth governance model.

Source authority, provenance, evidence, preservation, precedence, and conflict-resolution rules continue to apply.

See also: Source of Truth.