Metadata and compiled libraries
Metadata describes the contents of a compiled neoCLR assembly: its modules, types, functions, constants and references to other assemblies. It lets the compiler and editor understand a library without its source files, and lets the runtime resolve and check the code it executes.
One library, several uses
Suppose an application imports a separately compiled library. The compiler reads its public declarations and checks calls against their signatures. The editor uses those same declarations for completion and navigation. At execution time, the runtime binds the application's references to the supplied libraries and verifies instruction bodies. Reading a library's metadata does not run its application code.
Modules form namespaces for declarations. Assemblies package those modules and supply dependency identity. Two assemblies can declare modules with the same name without becoming the same owner.
The artifact layers
Native metadata and instructions are carried in a NEOX container. It can be stored as a standalone file or inside a PE file's #Neo stream. The layers separate file framing, payload encoding and the meaning of the declarations and instructions.
| Layer | Purpose |
|---|---|
| PE wrapper, when present | Carries metadata streams in a familiar executable-file container |
| NEOX envelope | Identifies versioned sections and their boundaries |
| Native payload | Encodes declarations, references and instruction bodies |
| Resolved program | Binds those references to the actual supplied dependencies |
The current binary payload uses a restricted CBOR object encoding. JSON remains a legacy/intermediate representation. Neither representation contains live objects, open files or other execution state.
Compatibility and validation
A PE file is not automatically a .NET assembly that the CLR can execute. neoCLR runs
the native model carried by #Neo; ordinary CLI tools may recognize the outer file
without understanding that model. The platform comparison explains
the broader relationship to .NET.
The runtime checks container structure and payload encoding, then resolves dependencies and verifies executable code. A file that parses successfully has only passed the first part of that process. Versioned contracts allow readers to reject features they cannot preserve rather than silently misinterpret them.
For application development, keep compiler, library and runtime artifacts together as shown in setup. Introspection exposes supported metadata views to programs; reflection adds controlled construction and invocation.
Implementing a reader or writer
The repository format specification covers byte layout, schema versions, size budgets, ownership validation and test evidence. The architecture guide explains how metadata fits into the platform.