145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# 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.
|