Release Compatibility Guide

Release compatibility ties together compiler, ABI, lib0x0, object, linker, and

optimizer artifacts. A release is compatible only when executable tests prove

that supported older artifacts either run correctly or fail with a documented

diagnostic.

Manifest Schema

Current manifest schema: 1.

Required fields:

0x0 v<version>
manifest_schema=1
trusted_version=<version>
abi_version=<version>
trusted_compiler=<path>
release_compiler=<path>
oisa_compiler=<path>
linker=<path>
archiver=<path>
lsp=<path>
source=compiler/main.0x0
abi_source=abi/VERSION
lib0x0_source=runtime/lib0x0.0x0
lib0x0_abi_source=runtime/lib0x0_abi.0x0
lib0x0_archive=runtime/lib0x0.a
linked_executables=build/release/v<version>/linker-fixtures/lib0x0-linked build/release/v<version>/linker-fixtures/lib0x0-direct
linker_fixture_hashes=build/release/v<version>/linker-fixtures/SHA256SUMS
optimizer_fixture_hashes=build/release/v<version>/optimizer-fixtures/SHA256SUMS
independent_fixture_hashes=build/release/v<version>/independent-fixtures/SHA256SUMS
manifest_schema_source=release/manifest-schema.tsv
diagnostics_doc=docs/diagnostics.md
compatibility_matrix=compat/abi-matrix.tsv
independent_compiler_source=compiler2/main.0x0
independent_compiler_encoding=compiler2/encoding.0x0
independent_compiler_object_format=compiler2/object-format.0x0
test_helpers=<space-separated packaged test helpers from release/test-helpers.txt>
memory_budgets=perf/memory-budgets.txt
memory_baseline=perf/memory-baselines/v<version>.txt
memory_report=build/release/v<version>/memory.txt
zero_next=build/zero-next
stage2=build/stage2
stage3=build/stage3
normal_path=trusted release compiler -> zero-next -> stage2 -> stage3
seed_path=bootstrap-from-seed audit/recovery only

release/test-helpers.txt is the source of truth for the test/tool helper list

used by test_helpers=. SHA256SUMS is the machine-checkable hash list for

manifest sources, packaged conformance helpers, and generated release artifacts.

Compatibility Matrix

The compatibility matrix must cover:

• compiler version;
• ABI version;
• lib0x0 source/runtime/archive version;
• lib0x0 source surface compatibility;
• object format version;
• archive format version;
• linker version;
• linker relocation compatibility, including local text-symbol relocations;
• optimizer level and default pass set.
• explicitly selectable optimizer pass compatibility.
• object-info, archive, and linker diagnostic compatibility.
• diagnostic classes shared by independent compiler implementations.
• installable release package layout and packaged helper coverage.
• independent compiler mixed-object ABI compatibility, including local

.text.local symbols that remain non-exported.

• independent compiler source and backend/mixed-link fixture compatibility,

including hashed evidence for compiler2 local object metadata.

• independent compiler canonical OISA API compatibility, including no-import and

package-import OISA comparisons against the main compiler.

• independent compiler cross-matrix source compatibility, including explicit

trusted->A, trusted->B, A->A, A->B, B->A, and B->B

ELF compiler-builder edges.

• independent compiler direct ELF compatibility, including compiler2-emitted

Linux ELF64 executables for the supported main -> I64 integer-literal,

local-call, and recursive-call slices, direct arithmetic/comparison/

conditional lowering, sequencing, local stack bindings, and same-file

argument passing, constant text-len/text-eq?, constant

text-at/text-slice, constant text character-class, and constant

int/text conversion lowering, plus

main -> Text literal and constant text-cat stdout output through

canonical compile-elf-program APIs.

• independent compiler same-object call relocation compatibility, including

R_X86_64_PC32 .rela.text metadata and I64 argument setup linked by

zero-link.

• independent compiler inline object compatibility, including compiler2-emitted

relocatable ELF objects for arithmetic, comparison, conditional, sequencing,

and local-binding expressions linked by zero-link.

• independent compiler imported external relocation compatibility, including

undefined global function symbols, imported I64 argument signatures, and

argument setup linked against main-compiler objects.

• independent compiler import export-list compatibility, including rejection of

unexported external calls before object emission.

• independent compiler archive compatibility, including deterministic archives

containing compiler2 objects whose local .text.local symbols are not

exported in the archive index.

Validation

make release-source-check is the lightweight release-engineering contract

gate. It verifies the release target, manifest schema, hash inputs,

package-layout scripts, normal-path audit, release-root/compat checks, and

release docs without building a release.

make ecosystem-source-check is the lightweight final-maturity contract gate.

It verifies the ecosystem gate, roadmap, documentation audit, normal-path audit,

and compatibility matrix without running the heavy gate.

make release-schema-check checks that release/manifest-schema.tsv covers

every field emitted by make release-metadata.

make release-helper-list-check checks that Makefile release helper hashes and

the manifest validation tests use release/test-helpers.txt, and that every

listed helper exists in the source tree.

make release-package-layout-check checks that release packaging includes the

installable docs, examples, tests, test/tool helpers, ABI, compatibility,

runtime, compiler source, and release schema files.

make release-compat-check checks manifest schema, every required manifest

field, release compiler/stage artifact presence, and hashes.

make compatibility-matrix-check checks the ABI/object compatibility matrix in

compat/abi-matrix.tsv, verifies every row has the expected schema, and rejects

rows that name missing Makefile gates. Release compatibility work must keep

both gates in agreement.

Public Docs And Site Compatibility

Public documentation compatibility is part of release compatibility when a

release changes documented behavior, public package names, public routes, or

domain behavior.

Release-blocking public docs gates:

make public-docs-milestone-9-check
make public-docs-milestone-10-check
make public-docs-drift-check

These gates verify route metadata, static search, redirect/archive behavior,

acceptance evidence, release checklist integration, bounded drift detection, and

completion evidence. Remote publication remains a manual release step and must

record rollback backups and public smoke results under deploy/static-sites/.

As later milestones land, the same gate must add object/linker/optimizer and

independent-compiler compatibility cases instead of creating separate release

promises.

Public Compatibility Note

Public documentation must distinguish source compatibility, package

compatibility, ABI compatibility, object/archive compatibility, runtime

compatibility, and site/registry compatibility.

Migration from jmp0x1b/lang and jmp0x1b/libs follows

docs/migration-policy.html. Old names, commands, syntax, or package ids are not

current 0x0 behavior unless this repository has matching implementation

evidence.