The Frozen Contract

The Frozen Contract

PWE is specified as a set of RFCs in rfc/. The words MUST / MUST NOT / SHOULD / MAY are normative. A decoder or runtime that cannot meet a MUST requirement fails closed: a defined error, no authoritative mutation.

v0.2.0

The v0.2 implementation contract contains the frozen set RFC-0019 … RFC-0036, plus later normative extensions (RFC-0037 bulk field sweeps, RFC-0038 pooled dynamic entities, RFC-0039 constraint joints, RFC-0040 soft bodies) and the earlier architecture/spec RFCs (RFC-0001 … RFC-0018).

Frozen at v0.2.0: WIR (0020), EIR (0021), Component ABI (0031), Runtime ABI (0026), Distributed State Machine (0024).

A compatible implementation MAY add an optional extension through the relevant extension rules; it MUST NOT reinterpret a defined bit, opcode, field, transition, status code, or ABI table slot.

Wire conventions

Unless an RFC says otherwise:

• multi-byte wire integers are unsigned little-endian
• lengths are byte lengths, counts are u32
• hashes are 32 raw SHA-256 bytes
• reserved fields MUST be zero when written
• u128 = two little-endian u64s, low then high
• native-language memory layout is never a wire format

Non-negotiable invariants

1. World is the single logical source of truth.
2. World Model and World State are separate.
3. Entity is identity; Component is data; System is behavior.
4. WIR is runtime-independent and EIR is hardware-independent.
5. Physics, Render, AI, and Sensor never own authoritative duplicate worlds.
6. Interpreter, JIT, and AOT share EIR observable semantics.
7. Cross-module mutation uses capability-bound views and the frozen ABIs.
8. A mutable entity has exactly one authoritative owner for one ownership epoch.
9. Incompatible schema, ABI, or artifact identities fail closed.
10. A successful transaction is the only way normal system writes become authoritative.

RFC map

RFC	Contract
0001	Architecture
0002	World IR
0003	Execution IR
0004	Component ABI
0005	World execution
0006	Distributed world
0007	Render IR
0008	Physics IR
0009	Compiler
0010	JIT / AOT
0011	Runtime ABI
0012	Memory layout
0013	Time & determinism
0014	Spatial interest
0015	Resource / asset
0016	Plugin / backend ABI
0017	Security & capability
0018	Version compatibility
0019	Schema & canonicalization
0020	WIR binary
0021	EIR binary and validation
0022	Memory & concurrency
0023	World transaction
0024	Distributed ownership state machine
0025	Snapshot & state delta
0026	Runtime ABI v0.2
0027	JIT contract
0028	Render-frame consistency
0029	Conformance tests
0030	Minimal reference profile
0031	Component ABI v0.2
0032	Domain IR
0033	Capability view ABI
0034	Errors, results, limits
0035	Artifact identity
0036	Interchange envelope
0037	Bulk field sweeps
0038	Pooled dynamic entities
0039	Constraint joints
0040	Soft bodies

Schema & serialization

Schemas are versioned and hashed. Breaking schema changes require explicit migration. Production binary formats are versioned + schema-aware + canonical + deterministic — no ad-hoc incompatible formats.

Changing the contract

RFC → conformance tests → implementation

If implementation and RFC disagree, the RFC and the conformance suite win. If the RFC itself is wrong, update it deliberately — never silently break a frozen contract.

Checklist before accepting an architectural change:

1. World remains the single source of truth.
2. WIR and EIR boundaries remain intact.
3. Kernel remains domain-neutral.
4. Deterministic execution remains possible.
5. Heterogeneous execution remains possible.
6. No stable ABI / schema / protocol is silently broken.

When in doubt: preserve semantics first, architecture second, performance third, convenience last.

See also: docs/rfc-alignment.md · docs/rfc-supersession.md · Determinism