Experimental Implementation
Part of the Sun ABI draft. Compatibility is experimental: compiler changes
may require rebuilding .moon libraries. There is no stable compatibility promise yet.
How it works
app → imports geometry.moon → calls area(Rectangle)Sun must check both the recorded rectangle declaration and the code that reads
its fields. If the metadata says a precompiled area exists but the function
body is missing, a valid-looking contract hash does not make the import usable.
Each .moon library carries one contract describing its target, required
compiler behavior, compiled layouts and calls, and retained generic code.
Sun checks this contract before importing the library.
For example, an x86-64 program cannot import a library built for AArch64. Likewise, a library requiring an unsupported compiler rule is rejected with rebuild guidance.
The compiler's supported rules come from src/abi/compiler_support.textproto,
validated and embedded during its build. Editing that manifest afterward cannot change an installed compiler.
What Sun checks
- The target and required compiler rules are supported.
- Decoded LLVM code matches the contract's recorded layouts, calls, and CPU requirements.
- Retained declarations and generic bodies match their recorded descriptions.
- Concrete class layouts and reconstructable function signatures agree with the compiled payload.
- Declaration references resolve across the selected imports, and advertised precompiled methods have bodies.
- Embedded dependencies retain their requirements.
For example, if metadata claims a precompiled method exists but its body is missing, import fails—even if someone recomputes the contract hash.
Declaration identity also matters: two libraries defining Point { x: i32 }
still define different Sun types. Matching memory layouts do not make them interchangeable.
These checks are incomplete: Sun does not yet independently verify every
relationship between source-level type metadata and compiled layouts.
Class and enum storage and Sun call signatures now share code with ABI validation.
For example, changing a recorded class field from i64 to i32 is rejected even
when the class is passed through a pointer and the contract hash is recomputed.
Types whose layouts depend on unavailable external declarations still need further checks.
Native archives
The draft accepts x86-64 and AArch64 archives: ELF on Linux GNU/musl, and Mach-O on macOS. It uses normal linker trust. Sun checks readable objects, matching targets, isolated symbols, and declared requirements. It does not audit instructions or maintain instruction, relocation, or external-symbol allowlists. The linker resolves native references.
For example, an archive calling malloc is allowed; an unresolved required symbol
still fails at link time. Archives with constructors or thread-local storage work
with native linking, but are rejected by the JIT, which does not yet support that lifecycle.
Producers can add requirements to an archive entry:
archives: [{
path: "libmath.a",
cpu_features: ["avx2"],
runtime: ["thread_local"]
}]These requirements are added to detected and inherited requirements. Unknown names fail packaging. Native builds validate CPU requirements against the generic CPU for the selected target, matching object emission, even when the build host supports more instructions. JIT imports use the executing host's capabilities. There is currently no custom destination CPU or feature override.
Compiler-generated AVX2/FMA kernels remain optional when every use is a direct
call guarded by the compiler's CPU-and-OS-state probe. Validation reconstructs
the probe body and checks that its successful branch dominates each call.
Unguarded calls, escaping kernel addresses, and additional instruction features
remain unconditional requirements. The compiler preserves a local guard even
for unsafe intrinsic calls; invoking one without support traps. Normal library
dispatch selects its ordinary fallback first. This recognition is deliberately
limited to the implemented AVX2/FMA probe, not arbitrary user-written dispatch.
Native archives continue to use producer-declared minimum requirements.
On Linux x86-64, when qemu-x86_64 is installed, CTest also executes the
linalg tests on an emulated CPU without AVX/FMA to exercise the ordinary fallback.
Why compatible-looking builds can be rejected
Compare two changes to the same geometry library:
| Change | Current result |
|---|---|
| A supported experimental rule has a different compiler fingerprint; payload and ABI checks pass. | Warn and continue. |
The llvm.bitcode hash differs; payload and ABI checks pass. | Warn and continue. |
| The reader contract matches, but LLVM cannot decode or verify the actual payload. | Reject the payload. |
| A field in metadata disagrees with its compiled storage. | Reject the concrete mismatch. |
Hash differences alone do not establish incompatibility. Decode, verification, and ABI failures identify concrete incompatibilities and remain errors.
The reader contract hash
requirements [read, materialize, verify, ...]
reordered requirements [verify, read, materialize, ...] → same canonical hash
comments or whitespace change → same canonical hash
requirement set changes → different canonical hashThese are abbreviated labels, not the actual protobuf enum names. A changed set must also pass the build-time check against the implemented obligations; editing the manifest cannot invent a reader implementation.
The llvm.bitcode requirement is the lowercase SHA-256 hash of a structured
BitcodeReaderContract defined in include/abi/compatibility.proto. Its values
live in src/abi/compiler_support.textproto and are validated against the
implemented reader obligations when the compiler is built.
The canonical encoding starts with a tagged sun.llvm.bitcode.contract domain,
followed by the distinct requirement enum values in ascending numeric order.
Each field has an unsigned 64-bit little-endian tag and byte length, followed by
its bytes: the domain uses tag 1 and UTF-8 bytes, and each requirement uses tag 2
and an unsigned 64-bit little-endian value. Protobuf serialization, comments,
whitespace, and declaration order are not hash inputs. Enum identities must not
be reassigned. Only changes to the requirement set change this identity; there
is no manually incremented bitcode version or compiler release number.
The consumer must decode, materialize, and verify every bitcode payload before import; unreadable or invalid payloads are still rejected. Separate Sun semantics, target, layout, and declaration checks remain required. Bundles using a different well-formed bitcode hash, including an old compiler fingerprint or prose-based contract hash, warn after these checks pass. The hash alone cannot establish whether the consumer can use the payload. Malformed or numbered bitcode identities remain unsupported.
Compiler fingerprints
Suppose a compiler helper moves to another source file without changing the library's layouts or calls. The implementation fingerprint can change, but that fact alone does not show that the library is incompatible.
Compiler fingerprints
Suppose a compiler helper moves to another source file without changing the library's layouts or calls. The implementation fingerprint can change, but that fact alone does not show that the library is incompatible.
Experimental compiler behavior carries an advisory implementation fingerprint: a hash of compiler sources, build settings, tools, and relevant libraries. A different fingerprint warns after payload and ABI validation, once per rule and exact bundle in a compilation. It does not by itself prove incompatibility. The warning acknowledges that experimental behavior remains unverified. Dependency merging allows these differences and retains the lexicographically smallest fingerprint as a deterministic representative.
This exception applies only to well-formed compiler fingerprints for implemented experimental rules. Bitcode hashes are separately advisory after payload and ABI validation. Other stable contract identities, unknown required capabilities, unreadable or invalid payloads, and verified target, layout, or declaration mismatches still cause rejection.
Coverage must include indirect dependencies. For example:
compiler tool → libLLVM.soChanging libLLVM.so can change generated code without changing the tool's own
executable. Fingerprints now follow these linked shared-library dependencies
recursively, and fail if one is missing or ambiguous. Discovery supports Linux
and macOS without library-loader overrides. macOS system libraries use the OS
build identity at build time and loaded image UUIDs at startup, because they may
exist only in Apple’s shared cache. Dynamically
loaded build-tool plugins and other undeclared build inputs still need coverage.
Reusing validation
If a bundle passes validation for an x86-64 native build, switching the same process to an AArch64 build must check it again. A cached “accepted” result is not portable to a different target or execution mode.
Preflight and actual imports share a compilation context, including the target, JIT or native execution, optimization settings, and ordered link options. Changing these settings clears authorizations. Nested builds keep separate state.
Producer versions are diagnostic only. An older producer may trigger one warning per imported bundle after validation; its version cannot make an incompatible library acceptable. Checking an existing output for build skipping does not warn.
Remaining work
- Finish shared descriptions for closures and interface dispatch, and metadata-to-code checks.
- Finish transitive fingerprint coverage.
- Test successful compatibility across historical compilers and libraries; current historical coverage only proves rejection.
Run sun --abi-info to inspect supported rules and profiles. Implementation lives
in include/abi/, src/abi/, and cmake/abi/; tests live in tests/abi/.
See the compatibility model for the full proposed design.