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.
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.