Development documentation · Some APIs may be unreleased Published release →

Guides

Introspection and Object contracts

TypeInfo describes a type's shape, generic arguments and supported member queries in the loaded program. Named declarations also provide NominalTypeInfo, including the declaration metadata shared with MemberInfo.

These APIs inspect metadata. Use the separate reflection operations to construct objects, invoke methods or access fields within the supported subset.

Nominal and structural type descriptors

TypeInfo does not inherit MemberInfo. Common code uses DisplayName and IsNominalType; only a NominalTypeInfo view exposes Name, FullName, Namespace, module/token, declaring type and custom attributes. Arrays and structural Function shapes do not implement NominalTypeInfo or MemberInfo. Named declarations, including constructed generic types, do. General shape and member queries remain on TypeInfo. Use NominalTypeInfo for declaration metadata and DisplayName for diagnostic text.

NominalTypeInfo.Namespace is the namespace name as a string. The inherited MemberInfo.Module: Optional<ModuleInfo> navigates to the assembly-scoped metadata module for that namespace; nominal runtime descriptors supply that owner. A matching namespace name in another assembly does not change this declaration's owner. The string name and module descriptor serve different queries; keeping both supports existing namespace-based compiler resolution without introducing another module kind.

Type identity

Repeated queries can allocate different descriptors of the same type. Both runtime descriptor providers apply represented-type identity through both Equals(TypeInfo) and Object.Equals(Object?). Generic arguments, element shape and loaded definition identity participate; a name or metadata token alone is insufficient.

Typed equality implements EquatableTo<TypeInfo>.Equals(TypeInfo), with no nullable operand. Object equality is the separate null-aware reference boundary: null and unrelated objects compare false. Object.ReferenceEquals still compares descriptor allocations. This follows the distinction between type identity and wrapper identity in .NET's Type APIs, without requiring CLR wrapper caching.

GetHashCode, called through Object, hashes the represented DisplayName with System.HashCode. Equal represented types have equal hashes. Distinct definitions with matching display names may collide; hashing never substitutes for equality. Hashes are not persistent identifiers and may change between runtime versions. ToString returns the represented FullName, rather than the runtime wrapper class name.

let first = typeof(int)
let second = typeof(int)
let view: Object = first
// Both compare the represented type, despite separate descriptor allocations.
first.Equals(second)
view.Equals(second)

The executable integration fixture also checks constructed generic types, arrays, wrong types, null at the Object boundary, HashMap callbacks and retention through GC. There is no general default comparer or cross-program descriptor identity contract.

Type relationships

Use source.AssignableTo(target) or target.AssignableFrom(source) when you need to know whether a value can be used as another type. Both require non-null TypeInfo arguments, just like typed Equals. They include identity, base classes, implemented interfaces and boxing to Object; they do not perform conversions.

IsSubclassOf(target) checks strict class ancestry: the same type and interfaces return false. IsInstanceOfType(value) checks an actual object's runtime type; its Object? argument intentionally permits null, which returns false.

let list = typeof(ArrayList<int>)
list.AssignableTo(typeof(List<int>))
typeof(List<int>).AssignableFrom(list)
typeof(Object).IsInstanceOfType(42)

Declared nominal interface variance admits compatible reference conversions between closed generic arguments; value arguments remain exact. Concrete generic classes and mutable array elements remain invariant. Function shapes compare by identity and are assignable to Object. Array covariance and open-generic constraint queries are not supported yet. These queries inspect types available in the loaded program; they do not load types or authorize reflective construction or invocation.

Logical modules

RuntimeContext.Current.ExecutingAssembly.GetModules() now returns flat logical modules in ordinal name order, including explicitly declared empty modules. A module is a namespace of declarations within an assembly; dotted names do not introduce parent links or recursive membership. ModuleInfo.GetTypes() returns retained types owned by the exact name, including nested types, with their original declaring-type ownership. Older images without a declaration table project retained types, free functions and constants; they cannot recover undeclared empty modules.

Type, member and parameter Module properties identify the same logical owner. Module identity remains full assembly identity plus logical name, within the loaded program. Migration: ModuleInfo.MetadataToken is removed. Physical image rows and their token scopes are separate metadata facts. Remaining type/member/parameter tokens describe physical definitions; pairing one with a logical module is not a replacement for physical scope information. No guest resolve-by-token API is provided. Rebuild the source libraries, reference assembly and runtime together.

Interpreter traversal is qualified by the Raven consumer. AOT supports NominalTypeInfo.Module for explicitly retained nominal type definitions through the existing private reflection-roots policy, reading the resulting Name, and following Module.Assembly to AssemblyInfo.Name/FullName. Assembly ownership is retained only for the exact module/assembly pairs reached from retained types. Unretained types fault with an explicit metadata-retention error. This does not grant constructor/method invocation. Explicit schema-4 moduleCatalogs roots additionally enable AssemblyInfo.GetModules for the complete declared names, including empty modules. Without that policy the call faults, even when some type owners are retained. Native RuntimeContext.ExecutingAssembly now preserves the calling code’s assembly, including library calls, and supports Name/FullName without reflection-roots flags. It does not implicitly retain module catalogs. AssemblyInfo.GetTypes, Module.GetTypes and module Object.Equals dispatch were not qualified by that initial slice. The later guest module-function retention qualifies namespace-scoped discovery on macOS ARM64; context-wide assembly discovery remains open.

The unstable Rust backend bridge neoclr::native_metadata::type_module(&Module, &metadata::Type) -> Result<Value, Fault> produces the same module descriptor recipe without allocating a guest wrapper or executing user code. Unknown types, absent/ambiguous catalog scope or invalid ownership return Fault. It is an in-repository compiler helper, outside the guest API and RavenDoc type selection; native snapshot factories materialize its result under explicit retention.

The unstable helper neoclr::native_metadata::declaring_type(&Module, &metadata::Type) -> Result<Value, Fault> returns the interpreter's optional enclosing-type recipe. Top-level declarations produce None; nested declarations preserve exact enclosing definition identity; unknown types return Fault. The native adapter answers only explicitly retained nongeneric declarations and faults for unretained handles. It grants no callable rights. Interpreter/JIT/AOT consumer and limits. This backend-only helper is outside guest RavenDoc selection; guest signatures are unchanged.

The development helper neoclr::native_metadata::base_type(&Module, &metadata::Type) -> Result<Value, Fault> returns the interpreter's optional base-type recipe. Native TypeInfo.BaseType queries use closed type tokens retained by the compiled program and return the same base identity or None; unretained handles fault. This grants no constructor or member invocation rights. The helper is outside guest RavenDoc selection and adds no guest signature. See the type-semantics experiment.

neoclr::native_metadata::has_value_type_base(&Module, &metadata::Type) -> bool checks the validated fieldless ValueType ancestry contract, including intrinsic value primitives and the additional Enum foundation for enum definitions. Native compilation can preserve it across private Object-root renaming using a compiler-only proof that serialized applications cannot supply. False means this special storage-category exception is unavailable; it does not grant general reference-base inheritance.

The same unstable backend bridge provides module_assembly(&Module, identity: &str, name: &str) -> Result<Value, Fault> and assembly_name(&Module, identity: &str) -> Result<Value, Fault>. These validate against the loaded catalog; missing assemblies or invalid module ownership return Fault. The AOT adapter admits only retained ownership pairs/full assembly identities, otherwise faults with native assembly ownership metadata was not retained. These helpers do not enumerate assemblies, load dependencies, or grant invocation. assembly_modules(&Module, identity: &str) -> Result<Value, Fault> returns the complete declared logical-module recipe, rejecting absent assemblies and legacy metadata without an explicit declaration table. The AOT adapter requires a matching catalog root, otherwise faults with native assembly module catalog was not retained. See the private retention policy. Catalog retention admits module ownership/name queries, not the contained types or callable bodies. No guest signature or RavenDoc type-selection change is required.

executing_assembly(&Module, facade: &metadata::Function, caller: &metadata::Function) -> Result<Value, Fault> is an unstable backend recipe helper. It uses the interpreter's scoped facade-skip rules and loaded catalog; missing caller/catalog metadata returns Fault. It neither executes the supplied functions nor loads assemblies. The native backend admits direct calls to the verified RuntimeContext getter. Binding the getter itself as a function is unsupported and diagnosed; ordinary function callbacks whose bodies query RuntimeContext retain their own assembly identity. The temporary lowering adds a private caller-identity argument, preserving call/callvirt and receiver checks. Source metadata and guest signatures remain unchanged.

The author's shared-namespace direction allows a module name to span referenced assemblies. Current ModuleInfo identity and its singular Assembly property describe an assembly-local contribution to that namespace. This does not require a separate aggregate descriptor. These APIs must not be interpreted as exclusive ownership of a namespace name; Namespace supplies the name and Module supplies scoped navigation.

Assembly and module identity

AssemblyInfo compares the full assembly identity in the current loaded catalog. ModuleInfo compares that identity together with its module name. Catalog validation ensures these keys are unique within one loaded program. Short assembly names, module names alone and metadata tokens are not sufficient keys. Repeated queries can allocate separate, equal wrappers; ReferenceEquals still compares allocations.

These contracts apply through Object.Equals(Object?). Null and other descriptor kinds compare false. GetHashCode hashes the same identity components with System.HashCode; collisions are allowed and hashes must not be persisted. Assembly display returns FullName; module display returns Name. This does not introduce nullable typed equality or a new EquatableTo interface on these descriptors.

.NET Assembly/Module describe loaded runtime entities, with loader contexts and runtime-specific identity. neoCLR currently has one descriptive loaded catalog and no dynamic assembly loading. Its full-name-based assembly equality is scoped to that model, not a promise of CLR loader equivalence. Additional load contexts would require an additional identity component. String hashing currently creates encoding temporaries.

The executable fixture checks repeated wrappers, Object dispatch and HashMap callbacks under collection pressure. A separate catalog regression uses assemblies with matching short names and module names but different full identities, plus multiple modules in one assembly.

Field, method and property identity

FieldInfo, MethodInfo and PropertyInfo implement Object equality using descriptor kind, closed declaring-type identity and definition index. Two queries for the same declaration compare equal even with separate wrappers. Different generic owners, different declarations and different descriptor kinds compare unequal. Null and unrelated objects compare false. There is no new nullable typed equality operand.

Their hashes combine kind, declaring DisplayName and definition index. Equal members have equal hashes; distinct type definitions with matching names may collide. Neither the hash nor DefinitionIndex is a persistent key. ToString returns the member Name; it does not format a .NET-style signature or uniquely distinguish overloads.

Current queries enumerate retained declarations on the requested type. They do not walk base types, even without DeclaredOnly; callers can inspect BaseType explicitly. The closed declaring owner is used for identity; no ReflectedType is exposed. This is narrower than .NET reflection, where reflected context can participate in equality. Generic method-definition queries still fault; the current equality contract does not add generic method instantiation support. Property accessor queries preserve the same method definition identity as direct method queries.

All three interfaces have generated member reference coverage. Queries describe metadata only: they do not read fields, invoke methods or execute accessors. Public application property metadata projection remains limited.

Parameters

ParameterInfo describes explicit method parameters and property index parameters. Object equality uses the closed declaring type, owner kind (method or property), definition index and zero-based position. Repeated queries compare equal; matching names/types/positions from different members do not. A property index parameter differs from its getter/setter parameter, including when their metadata token is the same. Tokens can be zero and are not equality keys.

GetHashCode combines the same owner components and position, hashing the declaring FullName. Distinct definitions with matching display names may collide. Hashes/indexes are not persistent IDs. ToString returns Name, which can be empty for missing names and current property index snapshots. Null and other object kinds compare false. ReferenceEquals still compares wrapper allocations; no nullable typed equality is added.

Ownership is retained internally as a compact key rather than a member/parameter object cycle. This adds a type descriptor and two integers to each runtime snapshot. There is no public Member property yet. .NET ParameterInfo exposes Member and Position, but its base class does not define owner-based Object equality; this is a deliberate neoCLR snapshot contract. A future Member property needs direct, scoped resolution without recursively materializing member/parameter graphs or enumerating unrelated members. Return parameters and optional/default values remain absent. Development attribute inspection is described below.

ParameterInfo and BindingFlags have generated member coverage. Binding flags select visibility and instance/static categories; they do not enable inherited traversal or grant member invocation access.

Type classification flags

TypeInfo exposes IsAbstract, IsOpen, IsClosedHierarchy, IsUnion, IsEnum and IsValueType. IsOpen means unrestricted inheritance/implementation, not generic openness. A closed family reports IsClosedHierarchy, while an ordinary leaf reports neither IsOpen nor IsClosedHierarchy. IsUnion is reserved for structural union identity. Nominal union declarations (including constructed Optional/Result) are identified separately by NominalTypeInfo.IsUnionDeclaration; cases return false. This development change replaces the former nominal meaning of IsUnion. Guest structural descriptors are available in the experimental interpreter through UnionTypeInfo and IntersectionTypeInfo. ClosedHierarchy describes the direct family; permitted open subtypes may themselves have descendants. These are descriptive metadata queries, not added raw-IL enforcement.

Runtime execution

Import System.Runtime.Reflection for checked construction and property execution. The descriptor interfaces remain descriptive. Execution accepts runtime-backed providers, returns Result for validation failures, and preserves terminal user Faults. Application instance properties and their original tokens are now projected; static properties remain outside the importer and init-only setters are omitted from assignment. Method/accessor visibility queries use retained source accessibility when available.

Development constructor discovery adds ConstructorInfo to the MemberInfo family. TypeInfo.GetConstructors() selects public instance constructors declared on the type; the flags overload allows descriptive visibility selection. Constructors expose parameters and visibility, without a method return type. See the Reflection API guide for execution limits.

Interface method flags

For admitted application interfaces, public instance defaults are virtual and have bodies (IsAbstract is false). Ordinary static helpers report IsStatic true and IsVirtual/IsAbstract false. Private helper visibility remains private; helpers do not create an implementation obligation on a class. This behavior is included in Reflection describes these methods; it does not enable general invocation of interface bodies or bypass their access checks.

Explicit application interface method bodies retain their qualified source names and private visibility. Query them using NonPublic, Instance and DeclaredOnly flags. Their IsVirtual flag is false: neoCLR represents explicit interface mappings separately from class virtual slots, unlike the CLI private/final/virtual emission flags. Ordinary public method queries exclude these private bodies. This development support does not add GetInterfaceMap or general reflection invocation of interface implementations.

Attribute data

MemberInfo.GetCustomAttributesData() and ParameterInfo.GetCustomAttributesData() return Sequence<CustomAttributeData> for directly declared, retained attributes. Types inherit this method through MemberInfo; fields, properties, constructors and methods use the same contract. No constructor or setter runs, and attributes are not inherited or merged. Multiple declarations retain metadata order; retrieval does not deduplicate them. Raven validates AttributeUsage on source declarations. An unannotated member/parameter returns an empty sequence.

CustomAttributeData exposes AttributeType: TypeInfo, Constructor: ConstructorInfo and GetConstructorArguments() -> Sequence<CustomAttributeTypedArgument>. CustomAttributeTypedArgument exposes ArgumentType: TypeInfo and Value: Object?, with an exact boxed String, Int32 or Boolean value (or null String). The argument sequence preserves constructor order and is copied on every call; descriptor objects expose no mutation.

Retention currently covers application-defined attributes in imported modules and the existing union marker. Compiler-only annotations and external framework attributes without admitted runtime definitions are not exposed. Unsupported user attribute constants and named arguments fail import. Attribute constructor bodies still need normal bridge admission. Runtime null constants are supported; Raven's nullable-string attribute constructor emission remains a known source limitation. There is no GetCustomAttributes instantiation API or inheritance option yet.

Development AOT now supports explicit custom-attribute data retention on macOS ARM64 and Windows x64, using the same descriptor/argument contracts. Int32-backed enum arguments retain nominal ArgumentType and expose their underlying boxed Int32 Value. Private reflection roots select metadata independently from invocation; unretained owners fault, while retained unannotated targets return empty sequences. Named String/Int32/Boolean field/property arguments are exposed by the matching development runtime library. This is a metadata-authored native gate, not compiler source-annotation integration or general discovery. Focused compiler-source emission checks pass independently. Native validation and limits.

Cache validated descriptions during startup for repeated mappings. Dynamic union case construction is a separate next step; this API alone does not install a route mapper.

TypeInfo.IsVisible: bool reports public visibility including containing types, element types and generic arguments. Missing imported visibility fails closed. Native definitions use declared visibility; primitives and generic parameter descriptors are visible. This is descriptive information, not invocation permission: open types and private members remain subject to their execution restrictions. The route-mapper case uses it to reject nonpublic schemas during preparation.

Attribute base constructor

protected Attribute() initializes a derived attribute. Only constructors of derived attribute classes may invoke it. System.Attribute is abstract; this constructor does not create attribute instances for metadata discovery. Use introspection to inspect attribute data without executing constructors.

Attribute type reference

Named attribute arguments (development 2026-10-10)

CustomAttributeData.GetNamedArguments() -> Sequence<CustomAttributeNamedArgument> returns assignments in metadata order without executing constructors, setters or other annotated code. Each call returns a fresh sequence; replacing entries in an array obtained by casting it does not change later results. An attribute without named assignments returns an empty sequence.

Member Contract
CustomAttributeNamedArgument.MemberName: string Exact field/property name.
CustomAttributeNamedArgument.IsField: bool True for a field, false for a property.
CustomAttributeNamedArgument.TypedValue: CustomAttributeTypedArgument Declared primitive type and boxed constant; null String stays null.

String, Int32 and Boolean named values are supported in interpreted and retained native execution. The metadata reader validates the target member and value before inspection. The .NET names and typed-value model are preserved; its MemberInfo property is a remaining gap, as are named enums, type/array constants and wider primitives. There are no public constructors or mutation APIs on these descriptors. Use matching runtime/library artifacts: the descriptor layout now includes the named snapshot. Older libraries retain fixed-only inspection and explicitly reject named data. See the tested consumer.

Module function selection bridge

native_metadata::module_function_definitions(&Module, identity: &str, name: &str) -> Result<Vec<metadata::MemberId>, Fault> is an unstable Rust backend helper, not a guest ModuleInfo member. It returns ownerless function definition identities in loaded metadata order for the exact assembly identity and module namespace. It includes all visibility levels and generic definitions, but excludes type-owned methods, child namespaces and instantiated generic bodies. Empty declared modules return an empty list. Unknown assemblies/modules, missing or duplicate definition identities and ambiguous legacy physical scopes fault. The native bridge requires an explicit declaration-module table; inferred legacy namespace catalogs are rejected.

Selection executes no bodies, loads no dependencies and grants no AOT retention or invocation rights. It supplies the definition keys needed for later signature and attribute descriptors. The helper alone does not provide in-process TestAttribute registration; the guest enumeration API is described below. This backend API is documented here manually; it is outside RavenDoc's guest class-library assembly.

The same unstable backend module also exposes:

  • module_function_snapshot(&Module, identity: &str, name: &str, definition: &MemberId) -> Result<Value, Fault>: a source-library MethodInfo recipe for an admitted free function, including its signature, parameter descriptors, token and module owner. DeclaringType is absent. A structural signature is used only as a private parameter identity key, matching the existing bound-function descriptor path.
  • module_function_attributes(&Module, identity: &str, name: &str, definition: &MemberId) -> Result<Value, Fault>: declared method-level CustomAttributeData recipes, including fixed and supported named arguments. Explicit parameter/return targets are excluded. Constructors and test bodies are never executed.

Both validate the definition against the explicit assembly-local module catalog and fault for foreign definitions. Open generic method signature snapshots currently fault explicitly; their attribute data can still be inspected. Unsupported attribute payloads or provider contracts retain the existing snapshot diagnostics. Recipes must pass the existing provider/materialization checks before becoming guest values; these helpers alone do not change native retention. Guest enumeration is described below.

Guest module functions

ModuleInfo.GetFunctions() -> Sequence<MethodInfo> enumerates directly declared free functions in the module's assembly and exact namespace, in loaded metadata order and without visibility filtering. It excludes type-owned methods, child namespaces and instantiated generic bodies. Empty modules return an empty sequence. Each descriptor has an absent DeclaringType and this module as its Module owner; GetParameters supplies parameter names, positions, types and ownership.

MethodInfo.GetCustomAttributesData() now reads method-level annotations for these ownerless descriptors, including supported fixed and named arguments, without executing attribute constructors or method bodies. Missing or ambiguous module/token matches fault. Open generic method signature snapshots remain unsupported and cause GetFunctions to fault; ownerless parameter/return attribute queries remain a gap. The compiled consumer demonstrates TestAttribute inspection. Interpreter and explicitly retained macOS ARM64 JIT/AOT execution are qualified. Development reflection-roots schema 5 adds moduleFunctions entries with exact assembly, namespace name, and Boolean customAttributes fields. Catalog retention alone grants no function metadata; attribute retention is separately opted in per function scope. Unretained queries fault. See the retention contract and executable checks. Windows, dynamic invocation and automatic registration are not qualified by this slice. The inherited attribute API and guest reference signatures are unchanged.

Host class dispatch helper (development 2026-10-11)

neoclr::native_metadata::class_implementation(module: &Module, concrete: &metadata::Type, contract: &metadata::Function) -> Result<metadata::Function, Fault> resolves a class virtual slot using the interpreter's ancestry rules. Use a verified complete load set. It returns the concrete or inherited implementation, preserving the declaring owner; invalid receiver ancestry, a nonvirtual contract or an unimplemented abstract slot returns a Fault. It does not invoke the method or permit dynamic loading.

This host-only helper supports AOT target selection and is not a guest reflection member. AOT keeps direct base calls separate from virtual dispatch, matching CLR call/callvirt semantics. Native metadata's TypeDef.is_sealed now means the type cannot be inherited; verification checks all definitions, even unreachable ones.

Structural composition descriptors (experimental, 2026-10-14)

UnionTypeInfo : TypeInfo and IntersectionTypeInfo : TypeInfo each expose Types: Sequence<TypeInfo>. This is a snapshot of the direct alternatives or bounds in normalized signature order. Mixed nested compositions retain their descriptor kind; closed generic constituents retain their generic arguments. Constituents are not generic arguments of the composition itself. Duplicate-only compositions normalize to the surviving type and consequently its ordinary descriptor.

These interfaces extend neoCLR's signature-level introspection model; .NET has no corresponding structural union/intersection TypeInfo. They have structural identity, not a nominal declaration or definition token. Equality and assignment use the runtime's existing composition rules. IsUnion is true only for UnionTypeInfo; nominal declarations use NominalTypeInfo.IsUnionDeclaration.

Availability requires the matching source-built System.Runtime library. The interpreter admits closed reference compositions; open generics and JIT/AOT composition execution remain outside this POC. Member, hierarchy and custom-attribute queries on direct compositions fault explicitly until their semantics are implemented. No fabricated nominal member set is returned. The obsolete CLI bootstrap remains unqualified for these providers.

Field storage and initialization

FieldInfo exposes IsInitOnly, IsLiteral and ConstantValue (Optional<Object>, currently boxed Int32 literals). GetFields includes static storage and constants according to BindingFlags; DefinitionIndex is a descriptor ordinal, not a storage opcode slot. MetadataToken retains the defining module's field token; older producers that omitted static tokens report None instead of inventing one. Names and generic field signatures remain descriptive even where reflection execution is unsupported.

TypeInfo exposes IsBeforeFieldInit and TypeInitializer (Optional<ConstructorInfo>). The latter is a private static constructor description, separate from ordinary methods. Neither property executes initialization. Native JIT/AOT constructor descriptions require explicit constructor metadata retention in reflection-roots schema 7.