# PBS - Compatibility and Evolution Policy v1 (Draft)

Status: Draft (Normative policy for language/runtime evolution)
Scope: Compatibility contract for PBS features across hardware/runtime updates
Language: English

## 1. Purpose

This document defines how PBS remains stable while the logical hardware evolves.

Goals:

- preserve existing cartridge behavior across updates,
- allow additive platform growth without silent regressions,
- keep evolution deterministic and verifier-friendly,
- define explicit upgrade/rejection rules for toolchains and firmware.

## 2. Authority and precedence

Normative precedence order:

1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. `PBS - Language Syntax Specification v0.md`
4. `PBS - Game Language Profile v1 (Draft).md`
5. `PBS - Game Profile Syntax Specification v1 (Draft).md`
6. This document
7. Legacy references (`docs/specs/pbs_old/*`)

If any rule here conflicts with higher authority, this document is invalid for that rule.

## 3. Core stability model

### 3.1 Frozen core contract

The following contracts MUST remain stable once released in a major line:

- frame synchronization semantics (`FRAME_SYNC` as deterministic safepoint),
- trap and verifier invariants,
- stack/call/return discipline for valid bytecode,
- deterministic scheduling and host-call contract rules.

Behavioral changes to frozen core contracts require a new major line.

### 3.2 Additive extension rule

New features SHOULD be additive by default.
Existing valid programs MUST keep their previous behavior unless they explicitly target a newer incompatible major.

## 4. Primitive and host API versioning

### 4.1 Canonical identity

Host-call primitives MUST be versioned by canonical identity:

`(module, name, version)`

An incompatible change MUST create a new `version`.
The old version MUST remain resolvable during its supported compatibility window.

### 4.2 No semantic retcon

Implementations MUST NOT silently change semantics of an existing canonical identity.
If semantics must change incompatibly, publish a new identity version and deprecate the old one by policy.

## 5. Cartridge target contract

Each cartridge/app manifest MUST declare, at minimum:

- target VM/runtime major (or compatible range),
- language profile and profile version,
- required canonical host-call identities and versions,
- required capabilities.

Loader behavior MUST be deterministic:

- load and run when all requirements resolve,
- reject with explicit diagnostic when requirements are missing or incompatible.

Implicit fallback to a different major/version is forbidden.

## 6. Evolution policy (major/minor)

### 6.1 Minor updates

Minor updates MUST be backward compatible.
Allowed examples:

- adding new host-call identities,
- adding optional metadata/diagnostics,
- adding syntax/features gated behind explicit profile selection.

### 6.2 Major updates

Major updates MAY introduce incompatible changes.
When this happens, maintainers MUST provide:

- explicit migration notes,
- compatibility window policy for prior majors,
- deterministic loader diagnostics for unsupported targets.

## 7. Compatibility layer policy

Runtime/firmware SHOULD provide compatibility shims for older identity versions for a defined window.

If shims are provided:

- shim behavior MUST be deterministic,
- shim scope and support horizon MUST be documented,
- shim removal MUST occur only in a new major line.

## 8. Toolchain requirements

Compiler/linker/tooling MUST:

- resolve host calls by canonical identity and declared version,
- fail deterministically on unresolved identities,
- emit target/profile metadata in output artifacts,
- avoid emitting instructions/features not supported by selected target contracts.

## 9. Conformance and replay guarantees

Each release MUST pass compatibility conformance suites that include:

- bytecode verifier invariants,
- host-call resolution checks by version,
- deterministic replay checks under fixed input/event traces.

For supported target contracts, the same cartridge plus the same input/event sequence MUST produce the same observable behavior.

## 10. Deprecation policy

Deprecation MUST be explicit and non-breaking during its support window.
Required stages:

1. Mark as deprecated (tooling warning + documentation).
2. Maintain compatibility through declared window.
3. Remove only in a subsequent major line.

## 11. Non-goals

- Defining subsystem-specific syscall tables.
- Defining game-stdlib API surfaces.
- Replacing runtime authority with PBS-layer policy.