Compatibility Model

Compatibility Model

Part of the Sun ABI draft. The examples explain proposed requirements; they do not promise a stable ABI in current releases. See Experimental Implementation for implemented checks.

The examples below use schematic descriptions, not executable Sun code. app is a program, and geometry.moon is a compiled library it imports.

Compatibility model

Start with one call:

geometry.moon: provides area(Rectangle)
app:           calls area(rectangle)

To make that call correctly, app needs to know how Rectangle is stored, how its argument is passed, and how the result is returned. Reading the function's name is not enough. These requirements belong to the library's bundle contract, together with its target, readers, runtime needs, and generic rules.

Now suppose geometry.moon embeds code from math.moon:

app → geometry.moon [geometry code + embedded math code]

If that math code needs a runtime service, the geometry contract MUST retain that requirement. Building geometry successfully on another machine does not make the requirement disappear. The producer MUST validate imports and reject combinations that cannot work together before emitting the new bundle.

There is one compatibility contract and hash for this complete bundle. Embedded artifacts MUST NOT require separate compatibility manifests or hashes. If app also imports a separate image.moon, Sun MUST check that bundle separately. Declaration and dependency identities still identify individual types and code; they are not additional compatibility contracts.

Compiler evolution

Suppose geometry uses ordinary integer arguments. A new compiler adds a vector calling convention, but geometry never uses it. That addition MUST NOT make geometry require vector support. The contract records what this bundle needs, not every feature its producer supports.

Small changeRequired behavior
A newer compiler still understands geometry's layouts and calls.Accept the supported bundle. Producer age alone MUST NOT reject it.
An older compiler reads a newer bundle that uses only rules it understands.Accept it when all required checks pass.
A compiler refactors its layout code without changing the defined rule.Preserve that rule's meaning and canonical encoding.
A new convention passes Rectangle through different argument storage.Introduce a distinct requirement; retain the old behavior if claiming to support old callers.
An omitted field used to mean “no extra CPU features.”MUST NOT give that omission a new meaning.
Metadata gains an optional diagnostic label.Keep it outside the compiled compatibility hash; older readers may skip it.
Metadata requires a reader capability the consumer does not implement.Reject it. Unknown required behavior is not an advisory fingerprint difference.

Producers SHOULD emit the oldest supported encoding sufficient for the bundle. Implementations SHOULD share code for unchanged rules; an old compiler copy per release is unnecessary. The support policy MUST list supported contracts and targets, announce removals, and explain rebuild or migration paths. The support window and notice period remain open decisions.

Automatic compatibility decision

Consider a hypothetical layout; the offsets here are illustrative:

geometry's compiled area(): reads Rectangle.height at byte offset 8
geometry's metadata:        says Rectangle.height is at byte offset 8
app's imported layout:     uses the recorded offset 8

These agree. If metadata instead says offset 4, Sun MUST reject the mismatch. Recomputing the metadata's hash cannot repair the compiled instruction that still reads offset 8.

For this import, the consumer MUST perform these checks before using imported layouts or emitting calls:

  1. Decode the container and required metadata with supported readers. A range extending past the file is an error, even if the filename ends in .moon.
  2. Check the target and required capabilities. An AArch64 library cannot supply x86-64 machine behavior merely because both targets have the same pointer width.
  3. Validate the contract description and its hash, and establish support for its required rules. The consumer MUST NOT trust a supplied hash as proof of support.
  4. Decode and verify the payload, then check declarations, layouts, call rules, ownership/runtime requirements, and retained generic bodies against it.
  5. Accept when those checks pass. A supported experimental rule with a different compiler fingerprint warns as described below; an unsupported required rule or a concrete mismatch fails compilation.

One readable LLVM module does not prove that its Sun declarations are correct. For example, a valid LLVM function can still have a signature different from that advertised by the bundle.

A cached result applies only to the checked input. Switching app from x86-64 to AArch64 MUST invalidate its earlier authorization. Cache keys MUST include artifact identity, contract hash, consumer implementation identity, target, and relevant options. Another bundle from the same producer MUST NOT inherit that authorization.

Native archives

Suppose geometry carries libmath.a, which calls malloc. That reference is allowed; the final linker must resolve it. If the archive calls a missing missing_helper, linking fails. Listing a symbol in diagnostic metadata cannot make its implementation exist.

Archive exampleRequired behavior
Its objects target another architecture.Reject the target mismatch.
It declares AVX2 as a minimum requirement, but the destination lacks AVX2.Reject the unsupported requirement.
It declares no extra CPU features.Treat this as the producer's claim of target-baseline support, not proof from disassembly.
It chooses an optional fast path only after a correct runtime CPU check.Permit dispatch under native-linking trust; do not require an instruction allowlist.
It requires native initialization in a JIT without lifecycle support.Reject before import.
It has a relocation the selected linker cannot handle.Report a link error.

The producer is responsible for its declared target, CPU, and runtime needs. Sun checks object format, architecture, symbol resolution, and runtime references where available. It does not prove that arbitrary native instructions obey the producer's claims. Native external-reference records are diagnostic only and MUST NOT form an additional import gate or compatibility-hash input.

Optional source recompilation

Suppose geometry contains x86-64 code, while app targets AArch64:

import existing x86-64 payload → reject for this target
explicitly rebuild complete source for AArch64 → validate the new artifact

This is a proposed optional path. Merely finding source in the bundle MUST NOT start a rebuild. The consumer must explicitly select recompilation or a fallback. It may also select a rebuild when the existing payload is compatible.

The source package needs supported source-language rules and complete build inputs. An exported generic body alone is not complete source: ordinary private functions, initializers, and embedded dependencies may also need rebuilding. Any binary-only native archive still needs its own supported target requirements.

A successful rebuild MUST produce a new artifact identity, references, and bundle contract. If another compiled library references the original geometry artifact, Sun MUST check those boundaries or rebuild that dependent code too. Rebuild-cache keys include source/build inputs, tool identities, target, options, and retained binaries. A missing generated input or failed rebuild MUST NOT authorize falling back to the unsupported original payload.

See complete source inputs for the remaining packaging design.

Computed ABI hashes

A hash identifies a description. For example:

contract A: Rectangle.height at offset 8, call rule X
contract B: Rectangle.height at offset 4, call rule X
 
canonical descriptions differ → hashes differ

The consumer still needs to read and validate those descriptions. Hash equality MUST NOT erase nominal type identity or skip declaration-reference checks. Two unrelated libraries can define equally shaped rectangles without defining the same Sun type.

The bundle hash uses SHA-256 over a canonical encoding of the domain, schema, target, and complete contract. The exact stable encoding remains to be specified; current encoding details are implementation behavior, not a stable ABI promise.

Encoding exampleRequired rule
Requirements appear in a different traversal order.Canonicalize sets so order alone does not change the hash. Preserve meaningful order, such as argument order.
The build directory changes from /a to /b.Incidental paths and timestamps MUST NOT affect the compatibility hash.
A protobuf library serializes the same values differently.Hash a defined canonical encoding, not incidental protobuf bytes or raw C++ memory.
A type contains a reference to itself.Encode stable declaration references; do not expand the layout indefinitely.
Someone edits metadata and supplies a matching hash.Independently check its required behavior and payload. Hash consistency alone MUST NOT authorize import.
The compiler emits a new runtime call.Derive the requirement from emitted code and retain it when embedding that code.

Field tags, lengths, integer encodings, ordering, defaults, and schema identity MUST be defined. Keep enough metadata to validate and inherit the contract. There are no separately accepted per-function, per-type, or embedded-artifact compatibility hashes. Adding optional source affects applicable source/integrity checks, not the compiled contract.

Stable contract changes need supported decoding and behavior, or migration. Different hashes do not establish release order. Experimental fingerprints are a special advisory input: they may change the recorded bundle hash without proving that its required ABI behavior changed.

Semantic fingerprints and warnings

Suppose two Sun builds implement the same Rectangle layout, but one reorganizes compiler source files:

producer's experimental fingerprint: aaa…
consumer's experimental fingerprint: bbb…
payload, target, and ABI checks:      pass
result:                              warn and continue

A source fingerprint cannot distinguish this refactor from a semantic change. Sun therefore MUST NOT reject an otherwise validated bundle solely because a well-formed fingerprint differs for an implemented experimental rule. The warning acknowledges that experimental behavior remains unverified; it is not a stable compatibility guarantee.

Contrast a different stable reader contract or an unknown required capability: those describe required behavior, not just a different compiler build. The consumer MUST reject unsupported requirements. Editing an expected hash or claiming that a release is compatible MUST NOT bypass those checks.

Fingerprints cover the responsible implementation, dependencies, relevant configuration, and tools. Omitting a helper because its source file is elsewhere would hide a real implementation difference. Missing or ambiguous build inputs must be resolved before claiming a complete fingerprint; an incomplete hash is not proof of equivalence. Stable semantics MUST eventually use defined rules and conformance checks rather than compiler-source fingerprints. Passing tests alone MUST NOT authorize an unsupported semantic contract.

Warnings and errors

For the same geometry import, these are different situations:

What Sun findsRequired result
All required checks pass; producer is older.Warn about age and continue.
All required checks pass; producer is the same build or newer.Continue; no age warning is required.
Checks pass, but build histories have unknown ordering.Warn that ordering is unknown and continue.
Checks pass, but an experimental compiler fingerprint differs.Warn about unverified experimental behavior and continue.
Metadata's field offset disagrees with the payload.Report the concrete mismatch and fail with a nonzero status.
Bitcode is unreadable, a required capability is unknown, or a stable contract is unsupported.Reject the compiled payload. A selected source rebuild must succeed and pass validation before use.
A legacy bundle has no contract.Reject unless a supported legacy decoder can reliably derive every missing requirement. Its format number is not proof of compatibility.

Warnings MUST follow validation. Emit at most one age warning per exact imported bundle and one fingerprint warning per rule and bundle per compilation. Embedded artifacts do not need separate age warnings. Age diagnostics name both compiler builds and the artifact. Errors name the bundle, its contract hash, and the unsupported requirement or concrete mismatch; “compiler versions differ” alone is not an adequate error. Failed compilation MUST NOT run or publish an executable as a successful result.

For example, a schematic fingerprint warning is:

warning: dependency geometry.moon has a different compiler fingerprint
  payload and ABI checks passed
  continuing with unverified experimental behavior

Official release ordering SHOULD come from release automation. Recorded source ancestry can order development builds; divergent histories remain unknown. Local file timestamps MUST NOT establish compiler age, and age never authorizes an otherwise invalid import.

Remaining design work

A stable promise still needs complete encoding and semantic specifications, extension defaults, historical acceptance tests, and a published support/removal policy. For example, “we accept last year's geometry bundle” needs a retained artifact tested with today's compiler, not two fresh builds made today. See Conformance & Implementation.