changes on docs and specs

This commit is contained in:
2026-03-24 13:42:17 +00:00
parent 6befcade91
commit a8f06922db
57 changed files with 0 additions and 0 deletions
@@ -0,0 +1,144 @@
# 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.
@@ -0,0 +1,106 @@
# PBS - Game Language Profile v1 (Draft)
Status: Draft (Language/Product direction)
Scope: PBS game-first language contract for 2D workloads
Language: English
## 1. Purpose
This document defines the language-level direction for PBS as a game-first scripting language.
The profile targets:
- intuitive onboarding for beginners,
- predictable frame behavior for real-time 2D games,
- explicit performance/cost surfaces for advanced developers,
- strict compatibility with a closed VM and its bytecode/runtime authority.
This document is language-contract oriented. It does not define bytecode encoding details.
## 2. Authority and compatibility
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. This document (Game Profile direction and requirements)
5. Legacy references (`docs/specs/pbs_old/*`)
If any rule here conflicts with runtime or bytecode authority, this document is invalid for that rule.
## 3. Design constraints
- The VM is a closed execution target.
- Language features must lower to supported VM/bytecode behavior.
- Determinism and frame synchronization are non-negotiable.
- GC is the baseline memory strategy.
## 4. Ten normative rules
### Rule 1 - Frame-first semantics
PBS game-facing language features MUST preserve deterministic frame execution.
Language constructs MUST NOT imply hidden asynchronous callbacks or preemptive execution.
### Rule 2 - Closed-VM compatibility
PBS MUST only define features that can be represented by the closed VM contract.
Language design MUST NOT require custom allocators, hidden host threads, or runtime behaviors outside VM authority.
### Rule 3 - GC-first memory model
PBS MUST treat GC-managed heap semantics as the default and beginner path.
Any future lifetime tools (such as pools/arena-like workflows) MUST be additive at API/library level unless runtime authority changes.
### Rule 4 - Explicit cost surfaces
PBS SHOULD make high-cost operations visible to users through language diagnostics and tooling contracts.
At minimum, allocation pressure, frequent host calls, and hot-loop risk points SHOULD be reportable in deterministic diagnostics.
### Rule 5 - 2D game-native type surface
PBS SHOULD provide a first-class game-oriented type surface through core language + standard library alignment.
The profile MUST support fluent expression of common 2D tasks (positions, velocities, bounds, colors, sprite/tile identifiers, frame counters).
### Rule 6 - Service boundary as gameplay architecture
`service` MUST remain the primary executable boundary for gameplay systems.
Language guidance SHOULD promote service-oriented decomposition for input, simulation, rendering orchestration, audio, and UI flows.
### Rule 7 - Typed host contract boundary
Host interactions MUST remain typed and explicit at language level.
Language constructs for host-facing APIs MUST preserve capability checks and syscall determinism from runtime authority.
### Rule 8 - Frame-based event and timer model
Game-facing event/timer language patterns MUST be frame-based and deterministic.
Language evolution MUST NOT reintroduce interrupt-like user execution semantics.
### Rule 9 - Progressive complexity in one language
PBS MUST support both beginner and advanced developers without forking into separate languages.
The beginner path MUST keep defaults simple and safe; advanced control MUST be explicit and opt-in.
### Rule 10 - Fluency for game loops
PBS syntax and standard patterns SHOULD optimize for high-frequency game-loop code:
- concise state updates,
- clear system boundaries,
- predictable data flow across update/render stages,
- minimal boilerplate for frame-driven logic.
## 5. Non-goals for this draft
- Defining new bytecode opcodes.
- Replacing runtime GC with a new mandatory memory subsystem.
- Adding language-level async callbacks or non-deterministic host behavior.
## 6. Planned follow-up specs
1. Game Profile syntax additions (if needed), layered on top of v0 Core.
2. Game-oriented standard library contract (collections, timers, ECS-adjacent utilities).
3. Tooling diagnostics spec for frame-cost visibility.
4. Host API declaration surface aligned with capability and syscall metadata.
@@ -0,0 +1,186 @@
# PBS - Game Profile Syntax Specification v1 (Draft)
Status: Draft (Normative for Game Profile parser/lowering work)
Scope: Syntax delta over `PBS - Language Syntax Specification v0.md`
Language: English
## 1. Purpose
This document defines the parser-facing syntax additions for the PBS Game Profile.
Goals:
- keep beginner usage fluid for 2D game construction,
- preserve deterministic/frame-oriented execution,
- remain compatible with closed VM + bytecode/runtime authority,
- avoid introducing hidden runtime behavior in language syntax.
## 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. This document
5. Legacy references (`docs/specs/pbs_old/*`)
If a rule here conflicts with higher authority, the rule is invalid.
## 3. Profile activation
Game Profile syntax is enabled by toolchain profile selection (`game` profile).
Without this profile, v0 Core syntax rules remain in effect.
## 4. Lexical delta (keywords)
### 4.1 Newly active keywords in Game Profile
- `host`
- `while`
- `break`
- `continue`
### 4.2 Still reserved in this draft
- `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
- `spawn`, `yield`, `sleep`
- `handle`
This draft does not activate heap-specialized syntax or coroutine syntax.
## 5. Top-level grammar delta
Game Profile extends top-level declarations with host function declarations.
```ebnf
TopDecl ::= TypeDecl | ServiceDecl | FunctionDecl | HostFnDecl
HostFnDecl ::= 'host' 'fn' Identifier ParamList ReturnType? ';'
```
Rules:
- `host fn` declares a host-provided call surface only (no body).
- Calling `host fn` lowers to syscall-linked call sites.
- Host functions are callable entities, never first-class function values.
- Service-shaped facades over host functions belong to stdlib design, not to host syntax.
Examples:
```pbs
host fn input_state(): (int, int, int);
host fn gfx_present();
```
## 6. Statement grammar delta
Game Profile adds imperative loop/control and assignment statements.
```ebnf
Stmt ::= LetStmt
| AssignStmt
| ReturnStmt
| IfStmt
| ForStmt
| WhileStmt
| BreakStmt
| ContinueStmt
| ExprStmt
WhileStmt ::= 'while' Expr Block
BreakStmt ::= 'break' ';'
ContinueStmt ::= 'continue' ';'
AssignStmt ::= LValue AssignOp Expr ';'
AssignOp ::= '=' | '+=' | '-=' | '*=' | '/=' | '%='
LValue ::= Identifier LValueSuffix*
LValueSuffix ::= '.' Identifier | '[' Expr ']'
```
Rules:
- `break` and `continue` are valid only inside `for`/`while`.
- Assignment is a statement, not an expression.
- `LValue` cannot contain function calls.
- Compound assignments are semantic sugar over read/compute/write.
## 7. Expression grammar delta
Game Profile adds postfix member/index access chains for fluent gameplay code.
```ebnf
UnaryExpr ::= ('!' | '-') UnaryExpr | PostfixExpr
PostfixExpr ::= PrimaryExpr PostfixSuffix*
PostfixSuffix ::= CallSuffix | MemberSuffix | IndexSuffix
CallSuffix ::= '(' ArgList? ')'
MemberSuffix ::= '.' Identifier
IndexSuffix ::= '[' Expr ']'
```
This replaces the v0 Core `CallExpr` chain and enables expressions such as:
```pbs
gfx_present();
player.transform.position.x;
tiles[i].id;
```
## 8. Determinism and lowering constraints
Game Profile syntax additions MUST preserve:
- deterministic control flow,
- verifier-friendly stack effects,
- explicit host call boundaries.
Lowering requirements:
- `host` call sites map to resolved syscall identities.
- `while`/`break`/`continue` lower to structured jumps compatible with verifier rules.
- Member/index read-write operations must lower to deterministic, type-checked access paths.
## 9. Diagnostics requirements (parser + early semantic phase)
Implementations MUST produce deterministic diagnostics for:
- `break`/`continue` outside loops,
- invalid `LValue` targets,
- duplicate host signatures in the same scope,
- unresolved host declarations at link/resolve stage,
- use of still-reserved keywords as active syntax.
## 10. Minimal canonical examples
### 10.1 Frame loop style with while
```pbs
host fn gfx_present();
fn run(): int {
let running = true;
while running {
update_world();
render_world();
gfx_present();
}
return 0;
}
```
### 10.2 Assignment and member/index access
```pbs
fn integrate(p: Vec2, v: Vec2): Vec2 {
let out = p;
out.x += v.x;
out.y += v.y;
return out;
}
```
## 11. Non-goals of this syntax draft
- Defining pool/arena memory syntax.
- Enabling `alloc/borrow/mutate` in surface syntax.
- Defining coroutine syntax (`spawn/yield/sleep`) before bytecode/runtime profile activation.
@@ -0,0 +1,373 @@
# PBS - Language Syntax Specification v0
Status: Draft (Normative for FE rewrite)
Scope: PBS v0 Core syntax (lexer + parser contract)
Language: English only
## 1. Goals
This document defines the canonical PBS v0 Core syntax.
It is designed to:
- be deterministic to parse,
- be stable for tests and tooling,
- align with runtime authority,
- provide a clear baseline for frontend rewrite.
This document defines syntax only. Runtime behavior, bytecode encoding, scheduling, and GC internals are out of scope.
## 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. This syntax specification
4. Legacy references (`docs/specs/pbs_old/*`)
If a syntax rule from legacy material conflicts with runtime or bytecode authority, that rule is invalid.
## 3. Source model
- Source encoding: UTF-8.
- Line terminators: `\n` and `\r\n` are both valid.
- Whitespace is insignificant except as separator.
- A source file is a declaration unit; top-level executable statements are forbidden.
## 4. Lexical specification
### 4.1 Tokens
The lexer must produce at least:
- identifiers,
- keywords,
- numeric literals,
- string literals,
- punctuation,
- operators,
- comments,
- EOF.
Each token must carry a source span (byte offsets).
### 4.2 Comments
- Line comment: `// ...` until line end.
- Block comments are not part of v0 Core.
### 4.3 Identifiers
Identifier:
- starts with `_` or alphabetic character,
- continues with `_`, alphabetic, or digit characters.
Keywords cannot be used as identifiers.
### 4.4 Keywords
Active keywords in `.pbs` files (v0 Core):
- `import`, `from`, `as`
- `service`, `fn`
- `declare`, `struct`, `contract`, `error`
- `let`
- `if`, `else`, `when`, `for`, `in`, `return`
- `true`, `false`
Barrel-only keywords:
- `pub`, `mod`
- `type`
Reserved (not active in `.pbs` v0 Core grammar, but reserved):
- `host`, `handle`
- `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
- `spawn`, `yield`, `sleep`
### 4.5 Literals
Numeric literals:
- `IntLit`: decimal integer (`0`, `42`, `1000`)
- `FloatLit`: decimal float with dot (`3.14`, `0.5`)
- `BoundedLit`: decimal integer with `b` suffix (`0b`, `255b`)
String literals:
- delimited by `"`.
- support escapes: `\\`, `\"`, `\n`, `\r`, `\t`.
Booleans:
- `true`, `false`.
## 5. Module and barrel model
### 5.1 Required files
A module is valid only if it contains:
- one or more `.pbs` source files,
- exactly one `mod.barrel` file.
Missing `mod.barrel` is a compile-time error.
### 5.2 Barrel responsibility
`mod.barrel` is the only place where module visibility is defined.
Visibility levels:
- `mod`: visible across files in the same module.
- `pub`: visible to other modules through imports.
Any top-level declaration not listed in `mod.barrel` is file-private.
Using `mod` or `pub` as top-level declaration modifiers in `.pbs` files is a syntax error.
### 5.3 Barrel grammar
```ebnf
BarrelFile ::= BarrelItem* EOF
BarrelItem ::= BarrelVisibility BarrelKind Identifier ';'
BarrelVisibility ::= 'mod' | 'pub'
BarrelKind ::= 'fn' | 'type' | 'service'
```
Rules:
- `mod.barrel` cannot declare aliases.
- Barrel item order has no semantic meaning.
- The same symbol cannot appear more than once in `mod.barrel`.
- Each barrel item must resolve to an existing top-level declaration in the module.
- Alias syntax is allowed only in `import` declarations.
- Importing modules may only import symbols marked as `pub` in the target module barrel.
Examples:
```barrel
mod fn clamp;
pub fn sum;
pub type Vector;
mod service Audio;
```
## 6. File and declaration grammar
EBNF conventions used:
- `A?` optional
- `A*` zero or more
- `A+` one or more
- terminals in single quotes
### 6.1 File
```ebnf
File ::= ImportDecl* TopDecl* EOF
```
### 6.2 Imports
Imports must target modules, never files.
```ebnf
ImportDecl ::= 'import' ( ModuleRef | '{' ImportList '}' 'from' ModuleRef ) ';'
ImportList ::= ImportItem (',' ImportItem)*
ImportItem ::= Identifier ('as' Identifier)?
ModuleRef ::= '@' Identifier ':' ModulePath
ModulePath ::= Identifier ('/' Identifier)*
```
Examples:
```pbs
import @core:math;
import { Vector, Matrix as Mat } from @core:math;
```
### 6.3 Top-level declarations
```ebnf
TopDecl ::= TypeDecl | ServiceDecl | FunctionDecl
```
Top-level `let` and top-level statements are not allowed.
### 6.4 Type declarations
```ebnf
TypeDecl ::= 'declare' TypeKind Identifier TypeBody
TypeKind ::= 'struct' | 'contract' | 'error'
TypeBody ::= '{' TypeMember* '}'
TypeMember ::= FieldDecl | FnSigDecl
FieldDecl ::= Identifier ':' TypeRef ';'
FnSigDecl ::= 'fn' Identifier ParamList ReturnType? ';'
```
### 6.5 Services
```ebnf
ServiceDecl ::= 'service' Identifier (':' Identifier)? ServiceBody
ServiceBody ::= '{' ServiceMember* '}'
ServiceMember ::= 'fn' Identifier ParamList ReturnType? Block
```
### 6.6 Functions
```ebnf
FunctionDecl ::= 'fn' Identifier ParamList ReturnType? ElseFallback? Block
ParamList ::= '(' Param (',' Param)* ')'
Param ::= Identifier ':' TypeRef
ReturnType ::= ':' TypeRef
ElseFallback ::= 'else' Expr
```
## 7. Type syntax
```ebnf
TypeRef ::= TypePrimary
TypePrimary ::= SimpleType | GenericType | TupleType
SimpleType ::= Identifier
GenericType ::= Identifier '<' TypeRef (',' TypeRef)* '>'
TupleType ::= '(' TypeRef ',' TypeRef (',' TypeRef){0,4} ')'
```
Runtime alignment:
- Tuple type arity in v0 Core is 2..6.
- This aligns with runtime multi-return slot limits.
## 8. Statements and blocks
```ebnf
Block ::= '{' Stmt* TailExpr? '}'
Stmt ::= LetStmt | ReturnStmt | IfStmt | ForStmt | ExprStmt
TailExpr ::= Expr
LetStmt ::= 'let' Identifier (':' TypeRef)? '=' Expr ';'
ReturnStmt ::= 'return' Expr? ';'
ExprStmt ::= Expr ';'
IfStmt ::= 'if' Expr Block ('else' (IfStmt | Block))?
ForStmt ::= 'for' Identifier 'in' RangeExpr Block
RangeExpr ::= '[' Expr? '..' Expr? ']'
```
Notes:
- `if` is a statement in v0 Core.
- `when` is an expression.
- `break` and `continue` are deferred from v0 Core syntax.
## 9. Expression grammar and precedence
Assignment is not an expression in v0 Core.
```ebnf
Expr ::= WhenExpr
WhenExpr ::= 'when' OrExpr 'then' Expr 'else' Expr | OrExpr
OrExpr ::= AndExpr ('||' AndExpr)*
AndExpr ::= EqualityExpr ('&&' EqualityExpr)*
EqualityExpr ::= CompareExpr (('==' | '!=') CompareExpr)?
CompareExpr ::= CastExpr (('<' | '<=' | '>' | '>=') CastExpr)?
CastExpr ::= AddExpr ('as' TypeRef)*
AddExpr ::= MulExpr (('+' | '-') MulExpr)*
MulExpr ::= UnaryExpr (('*' | '/' | '%') UnaryExpr)*
UnaryExpr ::= ('!' | '-') UnaryExpr | CallExpr
CallExpr ::= PrimaryExpr ('(' ArgList? ')')*
ArgList ::= Expr (',' Expr)*
Literal ::= IntLit | FloatLit | BoundedLit | StringLit | BoolLit
BoolLit ::= 'true' | 'false'
PrimaryExpr ::= Literal | Identifier | GroupExpr | Block
GroupExpr ::= '(' Expr ')'
```
Non-associative constraints:
- `a < b < c` is invalid.
- `a == b == c` is invalid.
## 10. Runtime authority alignment constraints
These are hard constraints for frontend and syntax decisions:
- Runtime is deterministic and frame-synchronized.
- `FRAME_SYNC` is runtime safepoint and not surface syntax.
- Heap semantics are GC-based at runtime authority level.
- Host interaction is via `SYSCALL` in bytecode and host ABI mapping.
- Syscalls are callable but not first-class.
Syntax implications for v0 Core:
- No RC/HIP/gate-specific syntax is active.
- No closure literal syntax in v0 Core.
- No coroutine syntax (`spawn`, `yield`, `sleep`) in v0 Core.
## 11. Deferred syntax (explicitly out of v0 Core)
Deferred for later profiles:
- heap-specialized syntax: `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
- first-class closure/lambda surface syntax
- coroutine surface syntax
- pattern matching
- macro system
These words stay reserved so later profiles do not break source compatibility.
## 12. Conformance requirements for frontend rewrite
A v0 Core frontend is conformant if:
- tokenization follows this lexical spec,
- barrel parsing and validation follows Section 5,
- parsing follows this grammar and precedence,
- parser is deterministic,
- each token and AST node keeps stable spans,
- forbidden constructs produce deterministic diagnostics.
## 13. Minimal canonical examples
### 13.1 Function
```pbs
fn sum(a: int, b: int): int {
return a + b;
}
```
### 13.2 Local function + barrel visibility
```pbs
fn clamp(x: int, lo: int, hi: int): int {
if x < lo {
return lo;
}
if x > hi {
return hi;
}
return x;
}
```
```barrel
mod fn clamp;
```
### 13.3 Imports
```pbs
import @core:math;
import { Vec2 as V2 } from @core:math;
```
+24
View File
@@ -0,0 +1,24 @@
# PBS Specifications (Current)
This directory contains the current PBS specifications for frontend and language work.
## Authority model
- Runtime authority: `docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`.
- Bytecode authority: `docs/specs/bytecode/ISA_CORE.md`.
- Legacy reference only: `docs/specs/pbs_old/*`.
When a rule conflicts with runtime or bytecode authority, runtime and bytecode authority win.
## Purpose
- Define a stable syntax contract for PBS.
- Support a full frontend rewrite (lexer, parser, AST, lowering).
- Keep grammar deterministic and implementation-friendly.
## Files
- `PBS - Language Syntax Specification v0.md`: normative syntax and grammar for PBS v0 Core profile, including mandatory `mod.barrel` visibility rules.
- `PBS - Game Language Profile v1 (Draft).md`: game-first language direction for 2D workloads, defining ten normative design rules aligned with the closed VM and GC-first baseline.
- `PBS - Game Profile Syntax Specification v1 (Draft).md`: parser/lowering syntax delta for Game Profile over v0 Core (host `fn` declarations, assignment, while/break/continue, member/index postfix access).
- `PBS - Compatibility and Evolution Policy v1 (Draft).md`: compatibility contract for PBS across logical hardware updates (frozen core rules, canonical versioning, target manifests, major/minor policy, replay/conformance guarantees).