# Compatibility Matrix and Published Claims Decision

Status: Superseded
Cycle: Conformance and compatibility agenda closure pass

Superseded by:

- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)

Superseded on: 2026-03-04

## 1. Context

PBS v1 needed one operational policy for how support claims are published, tested, aged, and retired over time.

The open questions from the conformance closure pass, especially Workshop 4, and from `17. Compatibility and Evolution Policy Agenda.md`, Workshop 3 were:

- what enters the regression corpus,
- which compatibility dimensions PBS must publish explicitly,
- what counts as a published support claim,
- how claims relate to conformance evidence,
- and how supported combinations retire without becoming ambiguous.

The adopted direction needed to ensure that compatibility tables and support statements are executable commitments rather than prose-only promises.

## 2. Decision

PBS v1 adopts the following baseline policy:

1. Published support claims must be represented by an explicit compatibility matrix.
2. Every published supported combination must be backed by maintained conformance or regression evidence appropriate to the claim level being published.
3. The regression corpus is not limited to bug reproductions; it also includes already-published normative examples, accepted behavior claims, and supported matrix combinations.
4. Unsupported combinations must be stated explicitly rather than inferred from silence.
5. Claim retirement must be deliberate: when support narrows or ends, the matrix entry, supporting tests, and migration/support note must all change together.

## 3. Compatibility Matrix Baseline

The minimum PBS compatibility matrix must expose, at minimum, the following dimensions where support is published:

1. language line,
2. stdlib line when reserved stdlib environment selection affects the claim,
3. runtime line when execution target selection affects the claim,
4. conformance claim level.

The matrix must also expose an explicit support state for each published combination.

The minimum support states are:

- `supported`
- `unsupported`
- `provisional`

Meanings:

- `supported` means the combination is promised by the publisher and backed by maintained evidence.
- `unsupported` means the combination is intentionally not promised and tools may reject or decline it without violating the published support policy.
- `provisional` means the combination is published as incomplete or experimental and must not be confused with ordinary stable support.

Silence must not be used where a published matrix exists and a reasonable reader could infer support.

## 4. Published Claims and Evidence

A published support claim exists whenever a publisher represents, in user-facing or tool-facing form, that a combination or behavior is supported, conforming, or maintained.

This includes, at minimum:

- a matrix entry marked `supported`,
- an unqualified or qualified PBS conformance claim,
- compatibility statements in product or release documentation,
- and published examples or fixtures presented as normative or supported behavior.

Every published claim must map to maintained executable evidence.

The evidence may be:

- conformance tests,
- regression tests,
- or both,

provided the evidence covers the claim scope actually being published.

`frontend conformance`, `source-runtime conformance`, and `full toolchain conformance` may therefore have different evidence sets, but each published claim still needs evidence inside its own scope.

## 5. Regression Corpus Policy

The regression corpus must preserve already-published behavior inside the scope of active support claims.

At minimum, the regression corpus must include:

1. bug reproductions for behavior that was fixed and remains within a supported scope;
2. published examples that are treated as normative or supported behavior;
3. accepted conformance claims and the behavior they promise;
4. supported compatibility-matrix combinations and their required outcomes.

The regression corpus may be organized into separate slices by claim level or domain.

What matters normatively is:

- published supported behavior is regression-protected,
- evidence remains attributable to the claim it protects,
- and narrowing support requires deliberate retirement rather than silent drift.

## 6. Retirement and Narrowing Policy

When a supported combination is retired or narrowed:

1. the matrix entry must change explicitly;
2. the old support state must not remain implied by stale documentation;
3. the corresponding evidence must be retired, reclassified, or moved to a historical/non-supporting corpus deliberately;
4. a migration, support-boundary, or rationale note must accompany the change when users could reasonably depend on the retired combination.

Retirement does not require one universal changelog format in this decision.

It does require that the support boundary become visible and reviewable.

## 7. Boundary Between `13` and `17`

The adopted split is:

- `13. Conformance Test Specification.md` defines the executable evidence obligations: what must enter the conformance or regression corpus and how supported claims become test-backed;
- `17. Compatibility and Evolution Policy.md` defines the publication policy: which matrix dimensions and support states are required and how supported combinations age or retire.

This keeps `13` test-oriented and `17` promise-oriented while ensuring both documents describe the same support contract.

## 8. Invariants

- Published support claims must be test-backed.
- A compatibility matrix is normative only when its states have executable meaning.
- `unsupported` must be explicit when omission would mislead users.
- `provisional` must not be mistaken for ordinary supported compatibility.
- Regression protection follows published supported behavior, not only bug history.
- Narrowing support is a deliberate policy act, not an accidental omission.

## 9. Explicit Non-Decisions

This decision record does not yet close:

- exact compatibility-window lengths by domain,
- exact migration-tooling triggers,
- PBX-specific binary compatibility policy,
- release tooling implementation,
- or one repository layout for matrix and regression data.

## 10. Spec Impact

This decision should feed at least:

- `docs/general/specs/13. Conformance Test Specification.md`
- `docs/general/specs/17. Compatibility and Evolution Policy.md`

It should also constrain later work in:

- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
- `docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md`

## 11. Validation Notes

The intended operational reading is:

- if a publisher marks one matrix row as `supported`, there must be maintained evidence for that row;
- if a combination is no longer supported, the matrix must say so explicitly rather than simply dropping mention of it;
- and if an example or claim is published as supported behavior, it belongs in the regression story even if it did not originate as a bug report.
