prometeu-studio/docs/pbs/specs/17. Compatibility and Evolution Policy.md

PBS Compatibility and Evolution Policy

Status: Draft v0 (Skeleton)
Applies to: compatibility commitments, migration boundaries, deprecation discipline, and evolution constraints across PBS language and related domains

1. Purpose

This document will define the normative compatibility and evolution policy for PBS.

2. Scope

This document is intended to define:

• compatibility promises across language, profile, stdlib, and artifact domains,
• migration boundaries for additive versus incompatible changes,
• deprecation and removal policy details,
• behavioral versus binary compatibility expectations,
• obligations when publishing changes that affect older cartridges or projects.

This document does not define:

• one repository's release workflow,
• one implementation's branching strategy,
• detailed changelog formatting.

3. Authority and Precedence

Normative precedence:

1. 1. Language Charter.md
2. 2. Governance and Versioning.md
3. Runtime and bytecode authority where applicable
4. This document

If a rule here conflicts with higher-precedence authorities, it is invalid.

4. Normative Inputs

This document depends on, at minimum:

• 1. Language Charter.md
• 2. Governance and Versioning.md
• 6.2. Host ABI Binding and Loader Resolution Specification.md
• 7. Cartridge Manifest and Runtime Capabilities Specification.md

5. Already-Settled Inputs

The following inputs are already fixed elsewhere and must not be contradicted here:

• Additive-first evolution is preferred for minor releases.
• Incompatible changes belong only in major lines with migration guidance.
• Canonical host primitive versioning uses (module, name, version).
• Toolchains must reject unsupported targets deterministically.
• Older supported cartridges are expected to keep running across updates.

6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. compatibility domains,
2. behavioral versus binary compatibility,
3. deprecation windows,
4. migration obligations,
5. compatibility-matrix expectations,
6. artifact and runtime compatibility boundaries.

7. TODO

The following items remain to be closed in future agenda discussion.

• Exact compatibility window by domain.
• Whether PBX/binary compatibility has an independent policy track from source-level compatibility.
• How stdlib-line compatibility interacts with dependency projects over time.
• Which changes require migration tooling versus documentation-only migration notes.
• Whether frontend-only phased implementation claims need distinct compatibility labels.

8. Non-Goals

• Replacing governance with ad hoc decisions.
• Defining one product release calendar.
• Freezing every editorial clarification as a compatibility event.

9. Exit Criteria

This document is ready to move beyond skeleton status only when:

1. compatibility commitments are explicit by domain,
2. deprecation and migration duties are normatively described,
3. source, stdlib, artifact, and runtime compatibility boundaries are separated clearly,
4. the document no longer relies on unresolved TODO items for ordinary v1 compatibility claims.