prometeu-studio/docs/specs/random/pbs/PBS - Compatibility and Evolution Policy v1 (Draft).md

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.