Development documentation · Some APIs may be unreleased Published release →

Guides

Experimental runtime hosting

Development API (2026-10-05), on codex/extended-cli-metadata. These Rust APIs are host-only; they are not guest System members or a stable native hosting ABI.

Explicit Object-root loading

impl LoadedProgram {
    pub fn with_modules_and_object_root(
        module: &Module,
        library: &Module,
        dependencies: &[Module],
        object_root: &metadata::TypeDefId,
    ) -> Result<Self, Fault>;
}

pub fn assembler::read_modules_with_object_root(
    inputs: &[ModuleInput<'_>],
    library: &Module,
    object_root: &metadata::TypeDefId,
) -> Result<Vec<Module>, Fault>;
  • module, or the first reader input, is the application. Additional inputs are dependencies. library is the retained System module without an entry point.
  • object_root selects a library definition by exact module name, optional revision and zero-based type row. It cannot select an application definition. The host must obtain this identity from its validated dependency catalog; a row is not stable across rebuilds and a revision label does not itself authenticate artifact contents.
  • The selected definition must be the only System.Object, public, abstract, fieldless, non-sealed, nongeneric, top-level, reference Record, with no base.
  • Required slots are public concrete virtual instance String ToString(), Boolean Equals(System.Object) and Int32 GetHashCode(), with ordinary receivers and parameters and no generic/interface implementation contracts.
  • Missing/duplicate roots, wrong identities, incompatible shapes/slots, malformed modules, missing references and inaccessible uses return Fault during loading. Existing visibility, native-service and instruction validation still applies.
  • With explicit selection, System may refer to supplied dependencies. Its reference list and uses are validated against the complete load set. Default loading retains its self-contained System requirement.

The reader returns the original separate artifacts, preserving scopes and identities. It validates a temporary linked copy. LoadedProgram keeps an immutable linked snapshot. Neither operation mutates input artifacts or executes guest code. Call verify() explicitly before execution; structural validation is not typed verification.

Selection is load-context state, never serialized in JSON, NEOX or PE/#Neo. It must be supplied again after reading artifacts. Existing read_modules, with_library, with_modules, new and free execution helpers do not select an external root. The CLI and Raven driver do not yet expose the option. Source Object compilation and metadata-writer root authoring remain pending.

The Rust Module now includes private transient context. Hosts previously using struct literals must construct artifacts through assembler/metadata readers or JSON deserialization; existing public metadata fields remain accessible. This is a Rust source-compatibility change, not an artifact-format change.

Example

Given application/System/Core artifacts whose identity catalog identifies the Object row in Core, select it explicitly:

let root = neoclr::metadata::TypeDefId {
    module: "Core".into(),
    revision: Some("r1".into()),
    index: 0,
};
let program = neoclr::LoadedProgram::with_modules_and_object_root(
    &application, &system, &[core], &root,
)?;
program.verify()?;
let execution = program.run(neoclr::Limits::default())?;

The matching revision and artifact-loading cases execute in tests/object_root_identity.rs. See the repository's docs/loaded-program.md for snapshot/execution lifetime and resource limits. This API does not authorize native P/Invoke; existing safe/unsafe execution boundaries remain unchanged.

Structural composition identity keys

On codex/structural-union-intersection, the Rust TypeIdentity enum adds:

Union(Vec<TypeIdentity>),
Intersection(Vec<TypeIdentity>),

LoadedProgram::resolve_type_identity(&Type) -> Result<TypeIdentity, Fault> (and the existing free resolution helpers) resolve admitted composition signatures in the standard runtime. Each constituent preserves its resolved definition key, including module/revision, row and generic arguments. Union and intersection keys are distinct; same-kind flattening, sorting and deduplication follow existing signature normalization. Duplicate-only compositions resolve to the surviving type. Mixed nesting is preserved. This is structural signature identity, not equality inferred from assignment or nominal ancestry.

Compositions nested inside admitted closed reference generic arguments retain their keys. Invalid, inaccessible, unresolved, open or disabled compositions return Fault; existing sealed-bound rules apply before intersection normalization. Keys belong to one resolved build and are not persistent cross-build identifiers. The new enum variants require downstream exhaustive Rust matches to be updated. This identity change does not alter the serialized metadata format.

A composition has no nominal definition row or declaring type. Internal definition token lookup returns no definition (token zero), never a constituent's token. Guest construction now selects UnionTypeInfo/IntersectionTypeInfo in the experimental interpreter, including nested descriptors inside admitted generic wrappers. See the guest contract. Member and hierarchy queries remain unsupported for direct compositions. These host Rust APIs are excluded from the guest RavenDoc selection and documented here.

Host composition descriptors

LoadedProgram::describe_type(&Type) -> Result<TypeDescriptor, Fault> now supports admitted closed compositions in the standard runtime. TypeDescriptor adds a public constituents: Vec<TypeDescriptor> field containing direct union alternatives or intersection bounds in normalized signature order. Other types return an empty vector. Inspect identity to distinguish Union from Intersection.

Each constituent is a complete recursive host snapshot with its own identity, name, generic arguments and constituents. For Box<union<Left,Right>>, Box remains a nominal descriptor with one generic argument; that argument has two constituents. For intersection<Box<Int32>,Left>, the Box bound has its own Int32 generic argument. Constituents are never reported as generic arguments of the composition itself. Direct compositions have no declaring type. Their diagnostic names use union<...>/intersection<...>; names are not identity keys. Normalization can collapse a duplicate-only composition to its remaining nominal descriptor.

Resolution checks visibility, feature admission and constituent validity before returning snapshots. Invalid inputs return Fault; inspecting snapshots neither executes guest code nor grants construction/invocation rights. Rust callers constructing TypeDescriptor literals must initialize the new field.

Guest type-token and TypeInfo providers retain the existing gate. In particular, the Raven TypeInfo.IsUnion property is now reserved for structural unions, while NominalTypeInfo.IsUnionDeclaration checks nominal metadata. Host description does not by itself enable guest structural descriptors. The guest API snapshot, native metadata encoding and CLI bridge are unchanged.

Experimental structural generic bounds (2026-10-14)

In the standard runtime, metadata GenericConstraint.kind may hold TypeBound(TypeUnion(...)) or TypeBound(TypeIntersection(...)) with the existing closed reference composition rules. Module::instantiated_fields and loaded generic method resolution enforce any-of/all-of membership after substitution, including full coverage of union arguments. Invalid arguments fault; bypassing verification does not bypass method constraint checks. Default builds reject structural bounds. The metadata preserves the structural bound, not multiple conjunctive nominal rows. No new guest constraint reflection API is introduced. See validation and limits.

Provisional dynamic Function lowering (2026-10-16)

pub fn function_invocation::lower(
    module: &Module,
    service: &metadata::Function,
    shapes: &[metadata::Type],
) -> Result<metadata::Function, Fault>;

Experimental runtime/compiler helper, not a stable native hosting ABI. It validates an InvokeFunction InternalCall contract and returns an ordinary checked IL adapter for the supplied closed structural function shapes. The caller must supply the reachable binding inventory and use the matching linked module. Duplicate shapes are deduplicated. Invalid service/shape metadata returns Fault; unsupported runtime inputs and signatures fault when the adapter executes. It neither executes code nor changes its inputs. It preserves the service identity and signature, clears the InternalCall flag and supplies the adapter body and initialized result local. See the primitive contract and validation.

The provisional function_invocation::lower adapter also accepts the reserved neoCLR.Runtime.InvokeFunctionCheck(Object, Object[]) -> Int32 contract. It performs no target call: status 0 means valid, 2 unsupported signature, 6 invalid receiver, and 8 invalid arguments. JIT/AOT use the same closed-shape adapter as the interpreter. This internal status protocol supports the public Result-returning FunctionReflection facade and is not a stable host ABI.