Versioning and Compatibility
Hexis versions the public contract separately from the mod build, script version, pack version, and documentation build.
Version identities
| Identity | Example | Purpose |
|---|---|---|
| API contract | 4.0 | Lua surface and runtime semantics |
| Mod build | 0.1.34 | Distributed implementation artifact |
| Script version | 1.2.0 | User workflow release |
| Pack version | 2.1.3 | Server-semantic compatibility |
| Capability version | navigation.go@1 | Registry schema evolution |
Scripts declare the API major and minor:
hexis.script({
api = "4.0",
name = "Example",
version = "1.0.0",
capabilities = {"navigation.go"},
})
The runtime rejects an unsupported API before ordinary script execution.
Compatibility rules
- Patch releases clarify docs and fix behavior without changing valid requests.
- Minor releases add optional fields, result data, codes, and capabilities.
- Major releases may remove or reinterpret behavior.
- Adding a required field is breaking.
- Changing a default with behavioral impact is breaking.
- Result consumers must ignore unknown
dataanddiagnosticsfields. - Stable top-level result fields and existing result codes do not change within a major version.
Capability schemas carry their own integer revision for generated compatibility reports. The public Lua name does not acquire a version suffix unless two semantics must coexist.
Deprecation
A deprecation record contains:
- first deprecated API version;
- replacement capability and migration example;
- reason and behavioral difference;
- earliest removal major;
- telemetry-safe usage signal.
Deprecated capabilities remain discoverable but rank below their replacement in AI tools. New generated scripts must not use them.
Pack compatibility
Packs declare supported API range, Minecraft range, server identity strategy, required engine features, and pack dependencies. A pack mismatch fails before the script starts or before an optional pack capability is selected.
Pack data can evolve without changing the core contract. A pack cannot redefine global result codes, resource semantics, permissions, or raw safety rules.
Promotion and rollback
A contract moves from contract to implemented only with an
implementation_ref tying it to source, tests, a distributed build, and live
acceptance evidence. Rollback removes the capability from discovery or restores
the prior implementation; it does not silently point a stable name at different
semantics.
Legacy v3
v3 pages are an archive, not a compatibility promise for v4. Migration is vertical: replace one production workflow, keep a narrow temporary adapter only where required, then remove the old binding family. The public docs never mix v3 calls into the runnable v4 AI bundle.