Development documentation · Some APIs may be unreleased Published release →

Guides

Experimental .NET metadata library

Experimental host tooling, separate from the neoCLR guest API. Assembly and namespace: NeoCLR.Metadata.Experimental. Target: .NET 10. Source project: tools/metadata/NeoCLR.Metadata.Experimental. This is the first reusable reader/writer slice intended for Raven's future symbol loader and code-generation adapters. It reads/writes NEOX 0.1 framing, structural signatures, reference tables and synthesized-member tables, and derives structural identities/member contracts against an explicitly supplied host catalog. Bounded PE32 recognition and a read-only manifest-module/TypeDef model are implemented; explicit AssemblyRef, nominal TypeRef and bounded method MemberRef resolution are implemented. A controlled primitive/root-object builder writes ordinary CLI PE and native format-5 assemblies, including native top-level functions. Direct PE/#Neo runtime loading uses a transitional native execution section with a reference-only CLI projection. A bounded binary native payload now avoids JSON parsing at runtime. General rewriting and guest Introspection assembly loading remain pending.

Declaration modules

AssemblyBuilder.DefineModule(string name) declares a logical module independently of the assembly name and returns a canonical DeclarationModuleDefinition. Name is its qualified path, Assembly the packaging owner, and IsProjection reports whether an older input supplied only namespace names. GetMembers() returns direct types, free functions and constants, excluding child modules and nested types.

On authored modules, AddClass(name), AddFunction(name, signature, visibility) and AddConstant(name, doubleValue, visibility) use that module as the declaration owner. Function/constant visibility defaults to public; existing public/internal restrictions apply. Loaded snapshots reject mutations with InvalidOperationException. Invalid names, duplicate members and existing builder bounds produce the corresponding ArgumentException; this slice does not introduce module-private access.

AssemblyDefinition.GetModules() returns logical modules in ordinal name order; AssemblyMemberDefinition.DeclaringModule identifies each direct owner. MetadataLoadContext.GetModules() discovers canonical module views in registered assembly order, then ordinal module-name order, without loading dependencies. AssemblyInfo.GetModules() enumerates the logical modules in one assembly. Empty logical modules survive native emission but not CLI projection. See format, limits and migration.

Context-owned declaration views

Namespace NeoCLR.Metadata.Experimental.Introspection. A ModuleInfo is a named unit of members within an assembly. Its name is the namespace of its declarations. Dotted names express a naming convention; metadata remains flat, with no parent links or synthesized parent modules. An assembly may package one or several modules.

API Contract
AssemblyInfo.GetModules(): IReadOnlyList<ModuleInfo> Logical modules in ordinal name order, including explicit empty modules. Read-only canonical context-owned views.
MetadataLoadContext.GetModules(): IReadOnlyList<ModuleInfo> All registered modules in assembly catalog order, then ordinal name order. No dependency loading.
MetadataLoadContext.Resolve(DeclarationModuleDefinition definition): ModuleInfo Canonical view for a registered definition. Null throws ArgumentNullException; an unregistered or different snapshot with the same assembly identity throws InvalidDataException.
ModuleInfo.Name: string Complete, case-sensitive logical name; empty for the global module.
ModuleInfo.Assembly: AssemblyInfo Canonical owning assembly.
ModuleInfo.IsProjection: bool True when inferred from older native/CLI namespace metadata.
ModuleInfo.GetMembers(): IReadOnlyList<AssemblyMemberInfo> Direct types, free functions and constants in assembly-member order. Excludes nested types, type-owned members and declarations in other modules, including dotted descendants. Typed views resolve lazily.
ModuleInfo.GetTypes(): IReadOnlyList<NominalTypeInfo> Nominal types belonging to this module, including nested types, in metadata order.
ModuleInfo.GetFunctions(): IReadOnlyList<MethodInfo> Direct free functions in metadata order, without visibility filtering. Unsupported callable signatures throw InvalidDataException; no invocation.
AssemblyMemberInfo.Module: ModuleInfo Canonical logical owner.
NominalTypeInfo.Module, MethodInfo.Module Canonical logical owner, inherited from the outermost declaring type for nested/type-owned declarations.
NominalTypeInfo.MetadataScopeName, MethodInfo.MetadataScopeName Physical metadata scope for interpreting MetadataToken. This is not a logical module identity; tokens may span multiple logical modules in one image.

All returned lists are read-only. Reference equality identifies a module within one context. The same name in another assembly or context is a different view. Signature and dependency resolution retains the existing typed-member errors. Assembly-wide GetTypes() continues to include all modules and nested types.

foreach (var module in context.GetModules())
    foreach (var member in module.GetMembers())
        Console.WriteLine($"{module.Assembly.Name}: {member.FullName}");

Development API migration: remove DeclarationModuleInfo, AssemblyInfo.GetDeclarationModules(), MetadataLoadContext.GetDeclarationModules() and AssemblyMemberInfo.DeclaringModule. Use ModuleInfo, GetModules() and Module directly. Callers needing a physical scope name use MetadataScopeName on types or methods, or the reader's ModuleDefinition. Assembly-wide callable scans must visit all modules. Test discovery IDs now include the logical module name instead of the physical filename. Rebuild host tools and the Raven native importer together.

Guest traversal through RuntimeContext.Current.ExecutingAssembly now uses the same logical model in the interpreter. Native support is limited to explicitly retained type-to-module descriptors; see guest contracts. This host change adds no metadata format, hierarchy table, compiler target switch or module reference table.

Unmanaged pointer signatures

SignatureType.PointerTo(elementType) creates an immutable unmanaged pointer signature. PointerElement exposes its target. Supported targets are scalar primitives (including Void), scoped type/method parameters, and nested pointers, up to sixteen pointer levels. Generic targets preserve their scope through substitution and native imports; closed substitutions must still have supported targets. String, RuntimeTypeHandle, nominal types, managed references and structural targets reject with ArgumentException; a null target throws ArgumentNullException. Pointer vectors, pointer generic arguments and pointer-bearing Function shapes are currently rejected. These bounds are library limitations, not changes to the CLI type system.

Use pointer signatures for callable parameters/results and local slots. Definition attachment and builder convenience methods share validation. GetILGenerator() preserves exact pointer target identity through arguments, locals, calls and returns; returning a different pointer target rejects during writing. This does not provide allocation, ownership, pointer arithmetic or dereference operations in the C# instruction API. Emit(OpCode.PointerCast, destinationPointerType) reinterprets a pointer without changing its address; both input and output must be supported pointer signatures. It emits native ptr.cast or CLI conv.u. Ceq accepts matching pointer types and returns Boolean without dereferencing either address.

CLI output uses standard ELEMENT_TYPE_PTR (including PTR VOID), and native output uses the existing Ptr category without a format-version change. Both readers preserve callable signatures and import them into new builders. MetadataLoadContext projects a canonical PointerTypeInfo, exposing ElementType, DisplayName and IsNominalType == false. No dependency loading or runtime reflection is required.

var pointer = SignatureType.PointerTo(PrimitiveType.Void);
var identity = owner.AddMethod("Identity", new MethodSignature(pointer, [pointer]));
var il = identity.GetILGenerator();
il.LoadArgument(0);
il.Return();

Validation: 162 C# metadata groups pass, including CLI/native round trips, manual method definitions, import, canonical introspection, depth/shape rejection and pointer target mismatch. An API-authored native assembly calls NativeMultiplyChecked, NativeAllocate and NativeFree and exits 42. Follow-up native module-function references also accept these pointer signatures via CreateFunctionReference; its explicit identity/digest contract remains unchanged. Raven now maps and consumes these callable signatures, and separately compiled source NativeMemory consumers execute. Pointer arithmetic and nominal pointer targets are still outside this bounded compiler gate; full System output remains pending. Source acceptance.

Generic classes over the native Object root

AssemblyBuilder.AddGenericClass(namespace, name, genericParameterNames, baseType, visibility) accepts this output's explicitly designated native Object root. The matching manual TypeDefinition constructor accepts the same local base reference. The base must already be attached; foreign roots reject. The initial Object-root-only scope has expanded to ordinary local bases and constructed bases; see the constructed and deferred base APIs below for current authoring contracts. Existing core-backed generic classes retain their behavior.

Constructors must explicitly call the root constructor exactly once before ordinary receiver access. Signature validation retains the full open generic receiver identity. Constructed instances may be passed to inherited root methods; type argument storage is preserved. CLI projection keeps the ordinary TypeDef base token; native metadata keeps the existing named base edge. No encoding/version change is required, and executable CLI output of a native Object root remains rejected.

The native reader preserves the base reference, and NominalTypeInfo.BaseType resolves the canonical root through the metadata context. The declaration fact applies to the generic definition; this does not add reflection or inherited member enumeration.

Validation includes definition/builder parity, base round trips, canonical facade identity, missing initialization rejection and executed generic storage plus inherited virtual dispatch. Source Raven regression and limits.

Namespace and types

These .NET-host-only types have this complete manual reference because the site's RavenDoc source is the neoCLR guest compiler-reference assembly. They are not omitted guest types or claimed executable neoCLR APIs. The maintenance record names this boundary explicitly; source XML documentation also ships beside the built .NET DLL.

MetadataSection

public sealed class MetadataSection
{
    public MetadataSection(ushort kind, ushort version, bool required,
                           ReadOnlySpan<byte> payload);
    public ushort Kind { get; }
    public ushort Version { get; }
    public bool Required { get; }
    public int PayloadLength { get; }
    public byte[] GetPayload();
}

The constructor requires nonzero kind and version and at most 1 MiB of payload. It copies the span into private storage. Invalid arguments raise ArgumentOutOfRangeException. The payload-size limit does not imply the section fits inside a complete envelope; headers also consume its 1 MiB budget.

Kind and Version identify the section schema. Required determines whether an exact schema match is required by the consuming layer. PayloadLength is the byte count. GetPayload() returns a new caller-owned byte array on each call; changing it or the constructor's original buffer cannot change this section. Payload semantics are not interpreted. A supported schema dictionary alone does not establish that a payload is valid or executable.

MetadataEnvelope

public static class MetadataEnvelope
{
    public const int MaxImageSize = 1048576;
    public const int MaxSections = 64;
    public static IReadOnlyList<MetadataSection> Read(
        ReadOnlySpan<byte> image,
        IReadOnlyDictionary<ushort, ushort> supportedSchemas);
    public static byte[] Write(
        IReadOnlyList<MetadataSection> sections,
        IReadOnlyDictionary<ushort, ushort> supportedSchemas);
}

Read takes one complete image. It validates magic/version, size/count limits, nonzero unique section kinds/versions, known flags, canonical contiguous ranges and required schemas. It returns a read-only section list with owned payload copies, in input order; the input buffer is no longer needed after the call. Unknown optional schemas are retained byte-for-byte. Unknown required schemas fail. An empty dictionary admits only optional sections. Callers must not mutate inputs during a call.

Write takes sections in desired output order, validates duplicate kinds, total size and required schemas, and returns a new caller-owned image. Empty envelopes and zero-length payloads are supported. Both operations reject malformed/unsupported framing with InvalidDataException; null list/dictionary arguments raise ArgumentNullException. A null section entry raises InvalidDataException. The helpers perform no file I/O or assembly loading.

The schema dictionary maps each kind to one admitted schema version. It is an explicit capability declaration supplied by the higher-level consumer, which must still decode and validate known payloads. These framing routines cannot be used by themselves as semantic acceptance for Raven or neoCLR. Preserving opaque bytes does not validate a rewrite of the declarations/tokens to which they might refer.

The current NEOX layout preserves section order and exact payload bytes and rejects gaps/overlaps/trailing data. Reading then writing a valid image therefore reproduces its bytes. This is deterministic framing, not structural type canonicalization. Copies simplify ownership at a memory cost; no zero-copy/performance claim is made.

Example and validation

The separate tools/metadata/MetadataConformance executable builds this example against the project reference and tests it through Python's independent reader:

var schemas = new Dictionary<ushort, ushort> { [7] = 2 };
var bytes = MetadataEnvelope.Write(
    [new MetadataSection(7, 2, true, "abc"u8),
     new MetadataSection(60000, 9, false, [0, 255, 0])], schemas);
var sections = MetadataEnvelope.Read(bytes, schemas);

Kinds 7 and 60000 here are opaque test payloads, not production declarations.

python3 docs/experiments/extended-cli-metadata/verify_dotnet.py

Four shared fixtures round-trip identically through .NET. Independently emitted .NET bytes match Python emission; both reject 49 malformed vectors. The consumer also checks required-schema mismatch, writer limits, unknown optional preservation and buffer ownership. The reference assembly/source snapshot check remains unchanged and passes; there are no new guest reference types in this slice.

TypeExpression

public sealed class TypeExpression
{
    public TypeExpression(string kind,
        IReadOnlyList<TypeExpression>? children = null, int index = 0,
        IReadOnlyList<string>? modes = null, bool noResult = false);
    public string Kind { get; }
    public IReadOnlyList<TypeExpression> Children { get; }
    public int Index { get; }
    public IReadOnlyList<string> Modes { get; }
    public bool NoResult { get; }
}

The constructor copies both lists into read-only owned collections. Children themselves are immutable nodes. Null lists mean empty. Null kind raises ArgumentNullException; null list entries, more than 257 children, or more than 256 modes raise ArgumentException. Do not mutate supplied lists while constructing the node. Construction alone does not validate a tree's shape: unknown spellings, inappropriate indices/modes and context-dependent errors are diagnosed by the codec.

Kind uses the exact lowercase spellings int32, string, bool, unit, type_parameter, method_parameter, self, array, array_ref, tuple, function, union, intersection, nullable, nominal. These are experimental wire syntax, not resolved runtime type names. Index is a zero-based generic ordinal, or a one-based nominal reference index, and must otherwise be zero. Children are ordered; Function parameters precede its last child, the result. Modes correspond to the parameters only: value, ref, readonly_ref, out, out_when_true.

NoResult applies only to Function and requires a plain unit result node. A unit result without this flag is inhabited. Conditional output requires a bool result. Other nodes cannot carry Function modes/flags. array and array_ref remain distinct. Unions/intersections retain order and duplicate children. This class has ordinary object identity; it does not implement structural equality, normalization or subtyping.

SignatureContext

public sealed class SignatureContext
{
    public SignatureContext(int typeParameters = 0, int methodParameters = 0,
                            bool selfAllowed = false);
    public int TypeParameters { get; }
    public int MethodParameters { get; }
    public bool SelfAllowed { get; }
}

Both counts must be 0–256 inclusive; other values raise ArgumentOutOfRangeException. Properties retain these immutable counts and Self permission. Parameter indices must be less than the corresponding count, and Self requires SelfAllowed. The context does not contain declaring type/method/contract identity and cannot establish runtime Self conformance or cross-module generic identity.

StructuralSignature

public static class StructuralSignature
{
    public static (TypeExpression Root, SignatureContext Context) Read(
        ReadOnlySpan<byte> payload, bool allowReferences = false);
    public static byte[] Write(TypeExpression root, SignatureContext context,
                               bool allowReferences = false);
}

Read consumes a complete signature payload, not an envelope or PE image. Write produces a new caller-owned payload array. Decoded objects are independent of the input bytes; callers must not mutate a span during reading. Both operations validate context, kind-specific shape, flags/modes, lengths and resource limits. Invalid or unsupported input raises InvalidDataException; null writer root/context raises ArgumentNullException.

Limits are 1 MiB per payload, 4,096 nodes, depth 32 with root at zero, generic arity 256 and 256 Function parameters/compound operands. Tuple requires at least one child; union/intersection at least two. Arrays and nullable require one; primitives, generic parameters and Self have none. The only supported calling convention is managed. Unknown nodes, flags, modes, trailing bytes and out-of-bounds counts fail.

With allowReferences: false, nominal nodes are rejected (section-1 profile). With true, the section-3 grammar admits a nominal index in 1–256 and up to 256 argument children. This is grammar permission, not a check that the reference exists, is a type or has matching generic arity; StructuralIdentity.Resolve performs those checks against an explicit catalog. Standalone byref-result syntax, full primitive support, declaration resolution, position legality, member synthesis and execution remain outside this codec.

The library preserves canonical payload framing, so valid read/write round-trips are byte-identical. Payload encoding does not normalize structural semantic identity. These type constructors and the following usage are exercised by the conformance consumer's signature commands:

var signature = new TypeExpression("function",
    [new("int32"), new("bool")], modes: ["out_when_true"]);
var bytes = StructuralSignature.Write(signature, new SignatureContext());
var decoded = StructuralSignature.Read(bytes);
python3 docs/experiments/extended-cli-metadata/verify_dotnet_signatures.py

Fourteen cross-reader vectors pass, including existing reference-profile fixtures, Function modes and nominal syntax. Independent .NET nested emission matches Python. Both readers reject 103 malformed vectors, including every nested-fixture truncation, invalid binders/Self contexts, unknown nodes/modes, bad conventions/flags, malformed lengths and depth/node limits. Writer/ownership and exact depth/arity boundaries are also exercised. None of these tests claims that the decoded metadata can execute.

MetadataReference and MetadataDefinition

public readonly record struct MetadataReference(Guid Assembly, Guid Module, uint Token);
public sealed record MetadataDefinition(string Kind, int Arity = 0,
                                        MetadataReference? Owner = null);

Positional constructors and matching public init properties store the given values. Records provide value equality, hashes, deconstruction, printable representations and with copies. They do not validate at construction; table/resolver operations validate before use. Default MetadataReference is invalid. Assembly and Module must be nonempty host-assigned scope UUIDs; Token must be a TypeDef (0x02) or MethodDef (0x06) token with a nonzero row. These scopes are not CLI assembly names, MVID-derived assembly identity or a promise that a token exists in a physical PE image.

Definition Kind is type, interface or method, with Arity 0–256. Only methods require Owner, a declaring-type reference. All other declarations require null Owner. The host supplies authoritative declarations, including referenced dependencies, and must use compatible scope assignments across catalogs when comparing resolved keys.

ReferenceBindings

public sealed class ReferenceBindings
{
    public ReferenceBindings(IReadOnlyList<MetadataReference> references,
        int typeOwner = 0, int methodOwner = 0, int selfOwner = 0);
    public IReadOnlyList<MetadataReference> References { get; }
    public int TypeOwner { get; }
    public int MethodOwner { get; }
    public int SelfOwner { get; }
}

Copies the list into owned read-only storage. Null references raises ArgumentNullException; more than 256 entries raises ArgumentException. Owners are one-based local indices, with zero meaning absent. Further validation occurs in ReferenceTable and StructuralIdentity. TypeOwner and SelfOwner must name TypeDefs; MethodOwner must name a MethodDef. References must be unique.

ReferenceTable

public static class ReferenceTable
{
    public static ReferenceBindings Read(ReadOnlySpan<byte> payload);
    public static byte[] Write(ReferenceBindings bindings);
}

Reads/writes section 2, schema 1: four little-endian u16 values for count/type owner/ method owner/Self owner, followed by 36-byte reference rows. UUID bytes use network order, tokens little-endian order. At most 256 rows are allowed; input must have the exact expected length. Invalid GUIDs, token kinds/rows, duplicates, owner kinds/indices, truncation or trailing bytes raise InvalidDataException. Null writer bindings raises ArgumentNullException. Read owns its data; Write returns a fresh caller-owned array. Neither resolves declarations or checks that nominal uses exist in the table.

StructuralIdentity

public static class StructuralIdentity
{
    public static ResolvedTypeIdentity Resolve(TypeExpression root,
        SignatureContext context, ReferenceBindings bindings,
        IReadOnlyDictionary<MetadataReference, MetadataDefinition> catalog);
}

Validates bounded signature syntax, reference-table rules, catalog kinds and arities, nominal generic arguments, and declaring owners before returning an identity. Null arguments raise ArgumentNullException; malformed or unresolved data raises InvalidDataException. Do not mutate the catalog during resolution. Every reference must resolve, including unused entries. A nominal use must point to a type/interface with the exact number of arguments. Generic binders require matching declaring-owner arities; a bound method's declaring type must match TypeOwner. Self permission must match the presence of SelfOwner, which must identify a nongeneric interface contract.

Generic parameters are keyed by declaring reference and ordinal; Self by contract. Local indices and table/directory order do not enter resolved identity. Unions and intersections flatten the same operator, discard duplicate operands and ignore order. A deduplicated singleton retains its operator wrapper. Tuples/arguments retain order; Function modes and no-result, and Array versus ArrayRef, remain distinct. This does not implement assignability, subtype reduction, distribution or null equivalences.

Callers select and validate the envelope profile: section 2/schema 1 plus section 3/schema 1 are required, and section 1 must not be mixed in. These payload-level APIs do not implement a production profile loader or PE recognition. They cannot establish that an assembly is safe to execute or populate Raven/neoCLR objects themselves.

ResolvedTypeIdentity

public sealed class ResolvedTypeIdentity : IEquatable<ResolvedTypeIdentity>
{
    public bool Equals(ResolvedTypeIdentity? other);
    public override bool Equals(object? obj);
    public override int GetHashCode();
}

Created only by Resolve; no public constructor or mutable state. Equals compares full resolved keys, returns false for null/other object types, and is consistent with the process-local hash. Use Equals or a normal equality-based collection; == is not overloaded. Neither hash codes nor private canonical bytes are persistence formats.

The separate conformance consumer exercises these APIs with Python-generated tables, signatures and explicit catalogs:

python3 docs/experiments/extended-cli-metadata/verify_dotnet_references.py

All 95 shared vectors pass: 22 equality/distinction cases, four table round-trips and 69 rejections. Independent C# golden UUID emission/reading, writer validation and list ownership checks also pass. The test-only JSON transport is not a library API.

StructuralMemberReference

public sealed record StructuralMemberReference(string Operation, int Owner = 1,
                                               int Element = 0);

The constructor and matching init properties retain values without validation. The record supplies value equality, hashes, deconstruction, printable representation and with copies. StructuralMembers validates before reading/writing/resolving: Operation must be array_length, tuple_element, tuple_deconstruct or function_invoke; Owner must be 1 (the section-3 root); Element is 0–255 and must be zero except for a zero-based tuple element. A reference is not a MethodDef token.

ResolvedMemberIdentity

public sealed record ResolvedMemberIdentity(ResolvedTypeIdentity Owner,
                                            string Operation, int Element);

A schema-1 identity comprising a resolved owner, operation and ordinal. Positional constructor/init properties and generated record equality/hash/deconstruction/with behave as value operations. The resolver returns validated identities; constructing one directly performs no validation and grants no capability. Equality compares full resolved owner identity, so local reference numbering is irrelevant but declaration scopes, array storage, Function modes/no-result and tuple ordinals remain significant. Hashes are process-local and neither identity nor its string form is a persistence API.

StructuralMemberDescriptor

public sealed class StructuralMemberDescriptor
{
    public ResolvedMemberIdentity Identity { get; }
    public IReadOnlyList<ResolvedTypeIdentity> Parameters { get; }
    public IReadOnlyList<string> Modes { get; }
    public ResolvedTypeIdentity Result { get; }
    public bool NoResult { get; }
}

Created only by StructuralMembers.Resolve, with copied read-only parameter/mode lists. Parameters exclude the receiver; modes correspond one-to-one in order. Result is unit when NoResult is true; a unit result with NoResult false is distinct. Descriptor object equality is ordinary reference equality; compare Identity for member identity and properties for contract content. No method body, dispatch target or invocation API exists.

StructuralMembers

public static class StructuralMembers
{
    public static ResolvedTypeIdentity NativeUnsignedResult { get; }
    public static IReadOnlyList<StructuralMemberReference> Read(ReadOnlySpan<byte> payload);
    public static byte[] Write(IReadOnlyList<StructuralMemberReference> members);
    public static IReadOnlyList<StructuralMemberDescriptor> Resolve(
        IReadOnlyList<StructuralMemberReference> members, TypeExpression root,
        SignatureContext context, ReferenceBindings bindings,
        IReadOnlyDictionary<MetadataReference, MetadataDefinition> catalog);
}

Read/Write encode section 4, schema 1: little-endian u16 count followed by six-byte rows (u16 owner, u8 operation, u8 zero flags, u16 operand). Operation codes 1–4 follow the order listed above. At most 256 unique rows are permitted, including an empty table. Read returns owned read-only rows; Write returns a fresh byte array. Table operations validate counts, exact lengths, operations, flags, owners, operands and duplicates, but do not validate owner shapes. Invalid data or null rows raises InvalidDataException; a null writer list raises ArgumentNullException.

Resolve validates the entire owner using StructuralIdentity.Resolve, even for an empty member list, then checks each operation's owner shape and derives these contracts:

Operation Owner Parameters/modes Result
array_length Array or ArrayRef None NativeUnsignedResult; NoResult false
tuple_element Tuple; ordinal within arity None Selected element; NoResult false
tuple_deconstruct Tuple All elements, each out Unit; NoResult true
function_invoke Function Declared parameters and modes Declared result and NoResult

NativeUnsignedResult is an intrinsic descriptor identity for native unsigned/UIntPtr, matching the experimental runtime ArrayLength contract. It adds no serializable signature opcode and does not claim ordinary .NET Array.Length's Int32 contract. Compare result identities with Equals. Resolve returns owned read-only descriptors in input order. Null arguments raise ArgumentNullException; invalid tables, unresolved catalog declarations, incompatible shapes or out-of-range tuple ordinals raise InvalidDataException. Callers must not mutate input lists/catalogs during operations.

Envelope composition remains the caller's responsibility: this member profile needs mandatory schema-1 sections 2, 3 and 4, with no local section-1 signature. These APIs do not perform artifact recognition, PE loading, assembly emission or runtime invocation.

The compiled consumer validates all public operations with 49 Python/.NET shared cases: 14 contract vectors, five identity comparisons and 30 rejections. Coverage includes 256 tuple elements/deconstruction outputs, empty tables, all Function modes, reference renumbering and malformed framing. Independent C# golden emission, writer rejection and reader ownership checks also pass.

python3 docs/experiments/extended-cli-metadata/verify_dotnet_members.py

MetadataProfile

public static class MetadataProfile
{
    public static MetadataProfileDocument Read(ReadOnlySpan<byte> image);
    public static MetadataProfileDocument Create(TypeExpression root,
        SignatureContext context, ReferenceBindings bindings,
        IReadOnlyList<StructuralMemberReference>? members = null,
        IReadOnlyList<MetadataSection>? optionalSections = null);
    public static byte[] Write(MetadataProfileDocument document);
}

These are the typed entry points for the reference profile, not a general CLI assembly API. Read requires mandatory schema-1 sections 2 and 3. Section 1 is rejected in any version, including when optional. A schema-1 section 4 must be mandatory when present. Unknown required kinds/versions fail; unknown optional payloads are retained opaquely, including future optional section-4 versions. Unsupported optional versions of sections 2 or 3 cannot satisfy the mandatory reference-profile requirements. A local-only, empty or incomplete envelope fails instead of producing a partial view.

Read performs envelope validation, signature/table decoding, local nominal index/kind checks, generic/Self owner presence checks, and member shape/ordinal validation. It owns the resulting data independently of the input buffer. It does not consult a catalog: nominal arity, declaring method ownership and Self interface requirements are checked later by the document's Resolve methods. Do not mutate input during a call. Malformed or unsupported input raises InvalidDataException.

Create accepts typed syntax, explicit local bindings and optional members. It copies through the codecs and performs the same local validation as Read. Null root/context/ bindings raises ArgumentNullException. Null members omits section 4; an empty list emits a supported mandatory empty table. OptionalSections accepts only non-null, optional sections with kinds greater than 4. Duplicate kinds, required extensions, reserved kinds 1–4, invalid shapes/references or exceeded bounds raise InvalidDataException. Output order is 2, 3, optional 4, then supplied extensions. All existing envelope/signature/table resource bounds apply.

Write accepts only a document returned by Read/Create and returns a fresh array. Null document raises ArgumentNullException. Read/Write preserves original order and all bytes, including opaque optional sections. Semantic editing is explicit: construct a new document and supply consistently remapped indices. Create does not copy unknown extensions automatically or claim their meaning survives changes. In particular, an unknown future optional section-4 payload can be round-tripped but cannot be attached to a newly constructed schema-1 document through optionalSections.

MetadataProfileDocument

public sealed class MetadataProfileDocument
{
    public IReadOnlyList<MetadataSection> Sections { get; }
    public TypeExpression Root { get; }
    public SignatureContext Context { get; }
    public ReferenceBindings Bindings { get; }
    public IReadOnlyList<StructuralMemberReference> Members { get; }
    public bool HasMemberTable { get; }
    public IReadOnlyList<MetadataSection> UnknownOptionalSections { get; }
    public ResolvedTypeIdentity ResolveType(
        IReadOnlyDictionary<MetadataReference, MetadataDefinition> catalog);
    public IReadOnlyList<StructuralMemberDescriptor> ResolveMembers(
        IReadOnlyDictionary<MetadataReference, MetadataDefinition> catalog);
}

No public constructor or setters. Sections contains all owned immutable sections; Root/Context/Bindings expose decoded syntax and owners. Members contains supported schema-1 rows. HasMemberTable distinguishes an absent/unsupported table from a present empty schema-1 table. UnknownOptionalSections exposes unrecognized sections without claiming to understand them; callers must inspect it when their own workflow needs additional semantics.

ResolveType returns full catalog-scoped identity. ResolveMembers validates the owner even when Members is empty, then derives supported contracts in table order. Both require a non-null authoritative catalog (ArgumentNullException otherwise); unresolved or incompatible declarations raise InvalidDataException. These methods do not cache or retain the catalog; do not mutate it during a call. No assembly loading or runtime object construction occurs.

This independently emitted example is compiled by the conformance consumer and matches the shared Python tuple-member fixture:

var document = MetadataProfile.Create(
    new TypeExpression("tuple", [new("int32"), new("string")]),
    new SignatureContext(), new ReferenceBindings([]),
    [new("tuple_element", Element: 1), new("tuple_deconstruct")]);
var bytes = MetadataProfile.Write(document);
var imported = MetadataProfile.Read(bytes);
var contracts = imported.ResolveMembers(
    new Dictionary<MetadataReference, MetadataDefinition>());

The focused consumer covers 36 shared profile vectors (29 rejections), independent creation/emission, owned data, optional preservation and explicit resolution failure.

python3 docs/experiments/extended-cli-metadata/verify_dotnet_profiles.py

The future Raven adapter and potential Raven implementation for Metadata Introspection are still planned. This one-root reference profile is not yet sufficient to represent complete assemblies, their declarations, IL bodies or all compiler signatures.

MetadataArtifactReader

public static class MetadataArtifactReader
{
    public const int MaxImageSize = 4 * 1024 * 1024;
    public static MetadataArtifact Read(ReadOnlySpan<byte> image,
                                        bool expectedExtended = true);
}

Read consumes complete PE bytes without loading or executing the assembly. The default requires a recognized extension: it rejects ordinary input and input with both markers removed. With expectedExtended false, input having neither a neoCLR. version marker nor a #Neo stream returns an ordinary classification. An unmarked #Neo stream, a marked image missing #Neo, unknown marker versions or inconsistent bindings always fail, regardless of that option. Automatic classification cannot recover erased provenance.

Supported input is deliberately restricted to the Python fixture transport contract: at most 4 MiB, 1–16 nonoverlapping sections, PE32 with a 224-byte optional header and 16 directories, supported power-of-two file/section alignment (512–65536 for file alignment), no overlay, no certificate directory or checksum, and a 72-byte CLI header with flags exactly IL-only and no strong-name/native-header directory. PE32+, signed and other unsupported layouts fail. This is not general-purpose PE validation.

The metadata root requires BSJB, an aligned version field of at most 256 bytes and at most 16 streams. Stream names must be nonempty, unique, ASCII, null-terminated within 32 bytes and zero-padded to four bytes. Stream ranges must be aligned, file-backed, outside the directory and nonoverlapping. All length/range arithmetic is checked before accessing input; oversized and truncated values raise InvalidDataException.

The recognized marker is neoCLR.NEOX.0.1;sha256= plus 64 lowercase hexadecimal characters and zero termination/padding. SHA-256 binds the domain separator and all exact stream names/data in ordinal name order, including #Neo padding. #Neo's declared envelope length must leave at most three zero padding bytes. The extracted envelope must then pass MetadataProfile.Read, so a valid digest cannot bypass required schemas or reference-profile validation. Local-only section-1 artifacts are not supported by this higher-level reader.

All malformed, inconsistent or unsupported inputs raise InvalidDataException. Read copies data needed by its result; callers must not mutate the span during the call. The result does not depend on the input buffer or a retained stream lifetime. Only span input is currently exposed; path/stream options and typed diagnostics remain future API work.

MetadataArtifact

public sealed class MetadataArtifact
{
    public bool IsExtended { get; }
    public MetadataProfileDocument? Profile { get; }
}

No public constructor or mutable state. IsExtended is true exactly when Profile is non-null: both recognition and local reference-profile validation passed. Ordinary classification has IsExtended false and Profile null. It does not expose ordinary CLI declarations or claim that conventional tables/signatures/bodies are valid.

The digest is a consistency check, not authentication, IL verification or an unaware-runtime execution guard. A writer can recompute it around changed conventional metadata; the reader deliberately does not claim to resolve or verify those tables. Future compiler use still requires physical CLI binding and declaration validation. The reader is a lower layer beneath the proposed Cecil-inspired assembly object model.

python3 docs/experiments/extended-cli-metadata/verify_dotnet_artifacts.py

The compiled consumer passes 50 shared Python/.NET cases (44 rejections), including Cecil's extension-stripping rewrite, marker erasure, rebinding, reordered streams, malformed ranges/names, wrong profiles, image-size limits and result ownership.

Model namespace

Assembly: NeoCLR.Metadata.Experimental; namespace: NeoCLR.Metadata.Experimental.Model. This first Cecil-inspired object-model slice is read-only and experimental. It uses the existing artifact recognition layer and System.Reflection.Metadata internally to read actual declarations, with no Cecil package dependency. It does not load runtime assemblies. These names are distinct from System.Reflection.Metadata and Mono.Cecil types; qualify or alias when needed.

AssemblyDefinition

public sealed class AssemblyDefinition
{
    public string Name { get; }
    public Version Version { get; }
    public AssemblyIdentity Identity { get; }
    public ModuleDefinition MainModule { get; }
    public MetadataProfileDocument? Profile { get; }
    public uint EntryPointToken { get; }
    public MethodDefinition? EntryPoint { get; }
    public byte[] Write();
    public static AssemblyDefinition ReadAssembly(ReadOnlySpan<byte> image,
                                                  bool expectedExtended = true);
}

No public constructor or setters. Name is the simple assembly name and Version is the manifest version. Identity adds culture, normalized public-key token and retained flags for exact explicit dependency matching (see below). MVID is not an assembly identity. CLR binding redirects, unification and trust policy are not implemented. MainModule is the owned manifest module; Profile is attached structural metadata, or null for explicitly admitted ordinary CLI input. EntryPointToken is a managed MethodDef token or zero for a library; nonzero tokens are checked against the method table. EntryPoint returns that same owned MethodDefinition instance, or null for a library. Write returns a fresh byte-for-byte copy of the original immutable snapshot, including opaque data. It does not rebuild declarations or apply edits. Use AssemblyBuilder for new controlled output.

ReadAssembly first applies MetadataArtifactReader's existing 4 MiB, unsigned IL-only PE32, stream and required-profile rules. The default requires extended metadata; expectedExtended false permits ordinary CLI assemblies. The method then reads the assembly and module rows, TypeDef names/namespaces, generic parameter counts and NestedClass ownership, AssemblyRef identities, and MethodDef names, ownership, flags, generic arities and owned signature blobs. It accepts at most 256 AssemblyRefs, a cumulative 4 MiB of key/token blobs, and at most 4096 TypeDefs and a cumulative 4 Mi UTF-16 code units of decoded declaration names/namespaces (counting repeated uses). It rejects missing/invalid or cyclic declaring-type relationships. MethodDefs are limited to 4096 and copied signature bytes to a cumulative 4 MiB shared with MemberRef blobs (including repeated references to one blob). MemberRefs are limited to 4096, require nonempty signature blobs, and have their parent table kind and row bounds checked. Missing/empty method signatures and instance global functions are rejected. Nonempty signatures outside the supported decoder remain opaque and are not generally validated. Missing assembly manifests (netmodules), invalid/unsupported artifacts and malformed inspected metadata raise InvalidDataException; underlying BadImageFormatException is retained as InnerException when converted. Callers must not mutate the span during reading.

The returned graph owns its strings/values and profile. Readers/streams are disposed before return; no assembly loading, dependency discovery or open resource remains. Only the inspected declaration subset is validated: this is not full signature, IL, attribute, constraint or execution verification. MetadataProfile's catalog scope UUIDs are not automatically derived from assembly names or MVIDs.

ModuleDefinition

public sealed class ModuleDefinition
{
    public AssemblyDefinition Assembly { get; }
    public string Name { get; }
    public Guid Mvid { get; }
    public IReadOnlyList<TypeDefinition> Types { get; }
    public IReadOnlyList<MethodDefinition> Methods { get; }
    public IReadOnlyList<MethodDefinition> Functions { get; }
    public MethodDefinition? GetMethodDefinition(uint metadataToken);
    public IReadOnlyList<MemberReference> MemberReferences { get; }
    public MemberReference? GetMemberReference(uint metadataToken);
    public IReadOnlyList<AssemblyReference> AssemblyReferences { get; }
    public IReadOnlyList<TypeReference> TypeReferences { get; }
    public TypeDefinition? GetTypeDefinition(uint metadataToken);
}

No public constructor. Assembly points back to the owning snapshot. Name/Mvid are the stored module values; Mvid is not an experimental catalog module scope. Types is an owned read-only collection of every TypeDef in row order, including nested types and <Module>. This intentionally exposes a flat table view in the initial slice; it does not promise Cecil's exact collection organization. AssemblyReferences is an owned read-only list of physical AssemblyRef rows in metadata order; reading it performs no resolver calls.

Methods contains all physical MethodDef declarations in row order. Functions contains those physically owned by the first, top-level, empty-namespace <Module> row. In the model these have null DeclaringType and the pseudo-type's Methods collection is empty. Other definitions retain their actual type owner. GetMethodDefinition returns the same snapshot object as these collections, or null for absent and non-MethodDef tokens. No overload selection or dependency lookup is implied. MemberReferences contains all physical MemberRefs in row order, including field/general signatures that this model cannot yet resolve. GetMemberReference returns the owned row or null for missing/wrong kinds; neither operation resolves a dependency.

GetTypeDefinition performs local physical TypeDef-token lookup and returns the same owned definition instance. Zero, other token kinds and absent rows return null. It does not follow exports or dependencies; TypeReferences exposes physical TypeRef rows for explicit resolution. At most 4096 TypeRefs and 32 enclosing TypeRef scopes are admitted; missing/cyclic parent and out-of-range AssemblyRef scopes are rejected.

TypeDefinition

public sealed class TypeDefinition
{
    public ModuleDefinition Module { get; }
    public uint MetadataToken { get; }
    public string Namespace { get; }
    public string Name { get; }
    public int GenericArity { get; }
    public TypeDefinition? DeclaringType { get; }
    public IReadOnlyList<MethodDefinition> Methods { get; }
    public TypeReference ToReference();
}

No public constructor. Module is the owning snapshot and MetadataToken its physical TypeDef address. Namespace/Name preserve metadata strings, including any backtick arity suffix; display names are not identity. GenericArity counts owned GenericParam rows, including captured outer parameters if encoded; it does not expose or validate the full generic constraint contract. DeclaringType links to the same graph's enclosing definition, or null for top-level types. ToReference creates a new definition-backed reference that resolves to this exact object. Methods exposes directly declared callables. Fields, custom attributes, base types and interfaces remain outside this slice.

MethodDefinition

public sealed class MethodDefinition
{
    public ModuleDefinition Module { get; }
    public TypeDefinition? DeclaringType { get; }
    public uint MetadataToken { get; }
    public string Name { get; }
    public ushort Attributes { get; }
    public ushort ImplementationAttributes { get; }
    public int GenericArity { get; }
    public bool IsStatic { get; }
    public byte[] GetSignature();
    public bool TryGetStaticInt32Signature(out int parameterCount, out bool returnsValue);
    public bool TryGetStaticPrimitiveSignature(out PrimitiveMethodSignature? decoded);
    public bool TryGetStaticValueSignature(out MethodSignature? decoded);
}

No public constructor or mutation. Module and DeclaringType refer to the same owned snapshot; null DeclaringType means a global function. TypeDefinition.Methods contains only its directly declared methods, not inherited or nested-type methods. MetadataToken is a physical MethodDef token, not cross-module identity. Name is the stored name; Attributes/ImplementationAttributes retain CLI flag bits and IsStatic tests bit 0x10. GenericArity counts method GenericParam rows without interpreting their constraints.

GetSignature returns a fresh copy of the CLI signature blob. It preserves unsupported encodings and never simplifies them into a supported signature. Returned bytes and original input bytes can be modified without changing the snapshot. No body, parameter names, custom attributes, constraints or general signature type resolution is provided by MethodDefinition. Use MemberReference for the supported reference-resolution subset.

TryGetStaticInt32Signature recognizes the original Int32-only writer contract: static, nongeneric, default calling convention, 0–256 Int32 parameters, and Int32 or absent CLI void result. Success sets parameterCount and returnsValue; false resets them to zero/false. Instance/generic/vararg headers, other types, noncanonical count encodings, truncation and trailing data return false. False means the narrow decoder cannot accept the signature; it does not distinguish a valid unsupported signature from malformed opaque data. ReadAssembly is not a general signature or execution verifier.

The C# consumer reads an emitted entry point, globals and overloaded type-owned methods, checks shared object identity and copy isolation, and covers counts 0/1/127/128/256, no-result returns, unsupported signatures, 4096/4097 rows and repeated-blob amplification.

MemberReference

public sealed class MemberReference
{
    public ModuleDefinition Module { get; }
    public uint MetadataToken { get; }
    public uint ParentToken { get; }
    public string Name { get; }
    public byte[] GetSignature();
    public MethodDefinition ResolveMethod(IAssemblyResolver? resolver = null);
}

The snapshot owns these rows; there is no public constructor or mutation. Module is the consuming module. MetadataToken is its physical MemberRef token; ParentToken is the physical MemberRefParent token, and Name is the referenced name. GetSignature returns a fresh copy, including opaque field or unsupported method signatures.

ResolveMethod supports the writer's static, nongeneric default-convention Int32/Int64/Boolean/String scalar/vector parameters (0–256) and scalar/vector/no-result contract. It resolves a local TypeDef or nominal TypeRef parent, requiring the explicit resolver for external scopes. It then selects exactly one directly declared method by ordinal name and decoded parameter/result contract, returning that target snapshot's owned MethodDefinition. There is no implicit filesystem probing, binding cache or access-policy decision. Resolver errors propagate; missing/wrong-identity dependencies, unsupported contracts/parents, and absent/ambiguous matches raise InvalidDataException. A return-contract mismatch cannot select a method.

Field, instance/constrained-generic/vararg and nominal signature types remain opaque. ModuleRef, TypeSpec and MethodDef parents are range-checked on read but unsupported for resolution. Global MemberRefs and inherited method lookup are also unsupported. Local global calls emitted by the writer use MethodDef tokens and remain available through method lookup. Resolution never compares module-relative nominal signature tokens as cross-module identity; general type-aware signature comparison remains future work.

C# tests resolve writer-emitted cross-assembly overloads and no-result methods, and exercise local TypeDef/TypeRef parents, copy isolation, missing/mismatched dependencies, return mismatches, ambiguity, host failures, unsupported signatures, invalid parents, 4096/4097 rows and the shared decoded-signature budget.

TypeReference

public sealed class TypeReference
{
    public ModuleDefinition Module { get; }
    public uint MetadataToken { get; }
    public string Namespace { get; }
    public string Name { get; }
    public uint ResolutionScopeToken { get; }
    public TypeDefinition Resolve(IAssemblyResolver? resolver = null);
}

Created from TypeDefinition.ToReference or a physical TypeRef row. Module is the target module for a definition-backed reference and the consuming module for a physical row. MetadataToken identifies that TypeDef/TypeRef in Module; Name/Namespace preserve stored metadata strings. ResolutionScopeToken is the physical scope, or zero for a definition-backed reference/nil scope.

Resolve returns the same owned TypeDefinition for a definition-backed reference. For physical references it supports local Module scope, exact AssemblyRef dependencies through the supplied resolver, and nested TypeRef scopes. Names/namespaces and nesting must identify exactly one target definition; missing or ambiguous targets, missing resolvers, nil/multi-module scopes or mismatched dependencies raise InvalidDataException. Host resolver exceptions propagate. Exported-type forwarders and TypeSpec/generic instantiation resolution are not supported. No implicit IO or assembly loading occurs.

All read-model classes use ordinary reference equality. Independent reads yield distinct graphs even when tokens/MVIDs match. Structural identity remains separate.

AssemblyIdentity

public sealed class AssemblyIdentity : IEquatable<AssemblyIdentity>
{
    public AssemblyIdentity(string name, Version version, string culture = "",
                            string publicKeyToken = "", uint flags = 0);
    public string Name { get; }
    public Version Version { get; }
    public string Culture { get; }
    public string PublicKeyToken { get; }
    public uint Flags { get; }
    public bool Equals(AssemblyIdentity? other);
    public override bool Equals(object? obj);
    public override int GetHashCode();
}

Immutable exact metadata-matching identity. Name is nonempty; Version has four components in 0–65535; Culture is the stored string (empty for neutral). PublicKeyToken is empty or 16 hexadecimal characters, normalized to lowercase. Flags retains metadata flags except PublicKey (bit 1), which expresses full-key versus token representation rather than identity. Null constructor inputs raise ArgumentNullException; invalid values or the PublicKey representation bit raise ArgumentException.

Equals uses ordinal name/culture comparison, exact version/flags and normalized token. Null and other object types are unequal. Hashes are process-local and consistent with Equals; == is not overloaded. This intentionally conservative policy does not implement CLR case folding, redirects, version roll-forward or retargeting. Nonmatching flags, including retargetable flags, fail exact resolution until a deliberate policy exists.

ReadAssembly converts a full public-key blob to the reversed final eight bytes of its SHA-1 hash, yielding the conventional key token. Assembly definitions require a full key with PublicKey set or an empty key with it clear; references permit a full nonempty key with the flag, or an empty/eight-byte token without it. Invalid representations raise InvalidDataException. Cryptographic key structure and signatures are not verified; token matching is identity comparison, not authenticity or execution permission. Original full keys, hash blobs and a complete writer representation are not exposed yet.

AssemblyReference

public sealed class AssemblyReference
{
    public ModuleDefinition Module { get; }
    public uint MetadataToken { get; }
    public AssemblyIdentity Identity { get; }
    public AssemblyDefinition Resolve(IAssemblyResolver resolver);
}

No public constructor. Module is the consuming module, MetadataToken its physical AssemblyRef token (0x23), and Identity the requested dependency identity. Resolve calls the supplied resolver, rejects null/missing or mismatched candidates, and returns the matching snapshot unchanged. Null resolver raises ArgumentNullException; missing or wrong identity raises InvalidDataException. Host resolver exceptions propagate without being disguised as malformed metadata. Calls are not cached; dependency search, IO, cache ownership and lifetime are explicit host policy. No runtime assembly is loaded by the reference itself. Nominal TypeRef lookup uses this resolver; constructed TypeSpec/forwarder binding remains pending.

IAssemblyResolver

public interface IAssemblyResolver
{
    AssemblyDefinition? Resolve(AssemblyIdentity identity);
}

The host receives the requested identity and returns a candidate metadata snapshot or null. It may choose how to obtain that candidate; AssemblyReference always rechecks exact identity. Implementations own their concurrency, cache and resource policy. Returning an arbitrary same-name assembly cannot bypass version/culture/key/flag checks. The C# tests include both a candidate resolver and a throwing resolver.

Run the standalone C# contract suite directly (no Python or test packages required):

dotnet run --project tools/metadata/NeoCLR.Metadata.Experimental.Tests/NeoCLR.Metadata.Experimental.Tests.csproj --no-launch-profile

The original 11 identity/resolution groups (now part of a 14-group suite) pass: physical AssemblyRef ownership, explicit resolution and repeat calls, missing/mismatched candidates, exact identity/hash rules, ECMA full-key/token golden normalization, constructor and wire validation, 256/257-reference boundary, owned data and exception propagation. Fixtures are real PE metadata images built in C# with System.Reflection.Metadata. This executable returns nonzero on any failure; it is not a dotnet test discovery project.

Controlled PE and native assembly construction

Namespace: NeoCLR.Metadata.Experimental.Model. These builders are the first writer part of the primary compiler abstraction. They construct new assemblies and allow body editing before another write; they do not rewrite arbitrary read snapshots or claim full Cecil compatibility. The current executable subset is top-level functions, public static classes and methods with Int32/Int64/Boolean/String parameters and Int32/Int64/Boolean/String or CLI no-result return. This is a compiler integration proof, not a complete language backend.

AssemblyBuilder

public sealed class AssemblyBuilder
{
    public AssemblyBuilder(AssemblyIdentity identity, AssemblyIdentity coreLibrary);
    public AssemblyIdentity Identity { get; }
    public AssemblyIdentity CoreLibrary { get; }
    public IReadOnlyList<TypeBuilder> Types { get; }
    public IReadOnlyList<MethodBuilder> Functions { get; }
    public MethodBuilder AddFunction(string name, int parameterCount = 0,
                                     bool returnsValue = true);
    public MethodBuilder? EntryPoint { get; set; }
    public TypeBuilder AddType(string @namespace, string name);
    public TypeBuilder AddType(string @namespace, string name, TypeVisibility visibility);
    public byte[] Write();
    public byte[] WriteNativeAssembly();
}

The constructor requires explicit output and core-library identities. Null raises ArgumentNullException; output identities with a key token or flags raise ArgumentException because signing/flagged output is unsupported. No host core library is inferred. The core supplies the System.Object base reference. Types is a read-only view of this mutable graph. Functions is its separate read-only view of top-level functions. Do not mutate participating graphs during either write operation.

AddType adds a public abstract sealed class with a unique namespace/name pair. Namespace may be empty; name must be nonempty and not <Module>. Combined length is at most 1024 characters and the assembly admits at most 4,095 declared types (plus the CLI module row). Invalid/duplicate inputs raise ArgumentException. EntryPoint may be null for a library or a local static Int32-returning or no-result method with no parameters or one String vector; it is checked at Write/WriteNativeAssembly. A no-result entry uses CLI void for ordinary PE output and native Void with no_result: true for format 5. Reference-only projections still have no CLI entry. The native declaration reader accepts both supported results and the optional String vector. Other parameter shapes, generic/foreign entries and ambiguous native entry names remain invalid, and no-result bodies must return with an empty stack. EntryPointChecks.cs verifies both global and type-owned entries, CLI invocation, native container roundtrips and failures; Raven's consumer also verifies native zero exit.

AddFunction creates an assembly-owned function with no declaring type. Names must be nonempty and at most 1024 characters, parameter counts 0–256, and an assembly admits at most 256 top-level functions. Duplicate name/parameter-count pairs raise ArgumentException. Function and type-method name scopes are independent.

Write validates every local body, assigns physical tokens/RVAs, imports foreign call references, and emits an owned unsigned IL-only PE32 image. Bounds: 4096 total methods, 131072 total instructions, 256 imported assembly identities and 4 MiB output. Foreign calls require the same core identity; an external dependency with the same identity as the output is rejected. Invalid bodies, entry points, incompatible imports or exceeded limits raise InvalidDataException. Call targets are typed builder methods; output references include exact assembly identity, nominal type name and method signature. Top-level functions are emitted as CLI global methods on the physical <Module> row; that row is a transport detail, not a declaring TypeBuilder. Local calls and global entry points are supported. Cross-assembly top-level calls currently raise InvalidDataException in PE emission; use native emission for that case.

Unchanged repeated writes of the same graph are byte-identical. Each builder has a fresh MVID, stable over its edits; equivalent independently constructed graphs need not have identical bytes. PE content IDs/timestamps are derived deterministically. No strong-name signing, resource/debug data, #Neo attachment or conventional-image rewriting is implemented by Write. The writer cannot silently discard such data because it accepts only its explicitly constructed subset, not an arbitrary loaded image.

WriteNativeAssembly validates the same local graph and emits owned UTF-8 bytes in neoCLR's existing JSON assembly format 5. Save as .neo.json and pass dependencies explicitly with --module; no PE importer, subprocess or runtime loading occurs inside the writer. Native top-level functions have no type owner. Type-owned methods retain an explicit owner. Both local and cross-assembly calls are supported; no-result returns remain distinct from inhabited Void.

Native output contains assembly/module/type/method origin metadata, scoped tokens, parameter-row absence (zero tokens), and exact dependency revisions. The transport module name uses SHA-256 of a canonical JSON identity tuple; member names encode UTF-8 bytes with ownership separators. This is deterministic binding, not authentication. The descriptive assembly identity retains name/version/culture/token/flags in that canonical tuple. Different dependency builder objects sharing one identity are rejected. Names used as native descriptions must be nonblank, free of control characters and well-formed Unicode; failures raise InvalidDataException. Output is bounded to 4 MiB. Native emission carries no MVID (format 5 has no such field), and does not attach NEOX structural sections or promise arbitrary CLR/PE compatibility. The explicit core identity is checked between builder call targets, but no core assembly is loaded for this primitive-only subset. This format-specific backend is provisional and will evolve with the native metadata format.

TypeVisibility (development 2026-10-01)

public enum TypeVisibility { Public, Internal } describes top-level static type visibility. AssemblyBuilder.AddType(namespace, name) remains public by default; its three-argument overload accepts only these two values and throws ArgumentOutOfRangeException for other values, before adding a type. Names, uniqueness and the 4,095-type bound retain the existing contract. TypeBuilder.Visibility is a read-only TypeVisibility property set at creation. Methods remain public static.

CLI output uses standard Public/NotPublic TypeDef flags. Native output retains the existing runtime visibility: "internal" and origin.publicly_visible: false for internal types; public output retains its omitted visibility default. The bounded native reader accepts old public artifacts and preserves visibility in its reference projection; unknown visibility or inconsistent origin flags raise InvalidDataException. Internal helpers can be called within the assembly but are inaccessible to external Raven consumers through the projection. No nested visibility, friend assemblies or nonpublic methods are added. This host API is separate from the guest API reference.

TypeBuilder

public sealed class TypeBuilder
{
    public AssemblyBuilder Assembly { get; }
    public string Namespace { get; }
    public string Name { get; }
    public TypeVisibility Visibility { get; }
    public IReadOnlyList<MethodBuilder> Methods { get; }
    public MethodBuilder AddMethod(string name, int parameterCount = 0,
                                   bool returnsValue = true);
}

Created only by AddType. Methods is a read-only view of owned methods in declaration order. AddMethod adds a public static hide-by-signature method. The legacy overload uses Int32 parameters; returnsValue selects Int32 or CLI void/no-result. The signature overload preserves Int32/Int64/Boolean/String parameter and result types. Names must be nonempty and at most 1024 characters; parameter counts are 0–256; a type admits at most 256 methods. Duplicate name/parameter-count pairs and invalid inputs raise ArgumentException. Generic methods, fields, instance receivers and signature variants are future work.

MethodBuilder

public sealed class MethodBuilder
{
    public AssemblyBuilder Assembly { get; }
    public TypeBuilder? DeclaringType { get; }
    public string Name { get; }
    public MethodVisibility Visibility { get; }
    public int ParameterCount { get; }
    public bool ReturnsValue { get; }
    public void LoadConstant(int value);
    public void WriteConsoleLine(string text);
    public void LoadArgument(int index);
    public void Add();
    public void Subtract();
    public void Multiply();
    public void Divide();
    public void Remainder();
    public void BitwiseAnd();
    public void BitwiseOr();
    public void BitwiseXor();
    public void ShiftLeft();
    public void ShiftRight();
    public void Call(MethodBuilder target);
    public void Return();
    public void ClearBody();
}

Created by AddMethod or AddFunction. Assembly always identifies its owning builder; DeclaringType is null for a top-level function. Body operations append conventional IL: Int32 constants, zero-based argument loads, arithmetic, static calls and return. Call accepts a method from this graph or another builder; null raises ArgumentNullException. Each append rejects more than 4096 instructions with InvalidDataException. ClearBody permits replacement without changing signature/ownership.

Write checks argument indices, typed primitive stack effects, call parameter/result contracts, a final return with the exact declared stack shape, and no earlier return. It derives max stack and rejects underflow, extra results or missing return. Loops, branches, general local types, exceptions and arbitrary raw IL are intentionally absent. Int32 locals are documented below. Runtime overflow behavior remains that of the selected target/bridge; this slice does not reconcile all CLR versus neoCLR arithmetic policies.

The C# writer consumer builds a dependency's Twice(Int32) -> Int32 and an application that calls it with 20, adds 2 and returns 42. It tests repeat writes, body edits, imported TypeRef/MemberRef resolution, entry-point ownership and invalid-stack rejection. Twenty-one standalone C# contract groups pass, including earlier identity/reference tests.

neoCLR acceptance test

The C# integration runner creates both PEs through the public builder API, invokes the existing Raven CLI bridge, assembles its output into a native .neo.json artifact, then asks neoCLR to load/verify and run that artifact. Expected result and process exit code are 42. No application IL or JSON is hand-authored for this test.

dotnet run --project tools/metadata/NeoCLR.Metadata.Experimental.Tests -- \
  --runtime-integration /path/to/neoclr /path/to/Probe.dll \
  /path/to/NeoCLR.CoreProbe.dll /path/to/System.neoil /fresh/output/directory

Inputs must be a matching runtime, bridge, core reference and composed Raven System library. The runner refuses an existing output directory and writes a report with artifact/tool hashes. It is a test CLI, not a library API. The bridge converts ordinary CLI signatures and bodies into the current native format; it does not enable native #Neo semantics. Direct PE/#Neo runtime loading and general compiler coverage remain separate work.

Direct native acceptance test

dotnet run --project tools/metadata/NeoCLR.Metadata.Experimental.Tests -- \
  --native-integration /path/to/neoclr /fresh/output/directory

The C# test emits a top-level Twice function in one assembly and a top-level entry function in another. It also exercises a no-result function, a type-owned method, argument loads and all three arithmetic operations. neoCLR directly verifies/loads these API-produced files and returns 42. Missing dependencies and incorrect revisions are rejected with the corresponding diagnostics. The runner preserves the artifacts and a hash report. This requires only the metadata test executable and native runtime, with its bundled System library; no Raven bridge or hand-authored application JSON is involved. See recorded evidence.

Importing a read-only callable

ImportedMethodReference AssemblyBuilder.ImportReference(
    MethodDefinition definition, AssemblyIdentity dependencyCoreLibrary);
void MethodBuilder.Call(ImportedMethodReference target);

public sealed class ImportedMethodReference
{
    public AssemblyBuilder Owner { get; }
    public AssemblyIdentity AssemblyIdentity { get; }
    public string? Namespace { get; }
    public string? DeclaringTypeName { get; }
    public string Name { get; }
    public int ParameterCount { get; }
    public bool ReturnsValue { get; }
}

ImportReference copies a static signature containing primitives, vectors, dependency-local reference types/constructions and optional unconstrained method parameters from an external read-only definition. No producer builder, body, runtime load or resolver is needed. Owner is the consuming builder; AssemblyIdentity is the exact dependency identity. The namespace and type name are null for a global function. ReturnsValue is false for no result. References expose no body editing or signature mutation.

The caller must supply the dependency's core-library contract explicitly; it must equal the consuming builder's CoreLibrary. This is a host assertion, not a deduction from CLI primitive bytes or a verification of the dependency's implementation. Native dependencies must be separately supplied and use this writer's format-5 naming contract. PE output uses ordinary AssemblyRef/TypeRef/MemberRef rows for type-owned methods. Cross-assembly globals remain native-only. Access checks are not performed.

Nominal signature tokens must identify public top-level unconstrained invariant reference types in that dependency snapshot (TypeDef). TypeRef signatures require a future explicit resolver contract. Value types, nested/generic owners, instance/constrained-generic/other signatures, signed or flagged dependency identities and imports of the output identity throw InvalidDataException. A single builder admits at most 256 imported assembly identities and 4096 imported methods. Different module MVIDs under one identity, or differing callable contracts under one MVID/token, are rejected. Repeated compatible imports return the same reference; MVID consistency is not content authentication. Null arguments throw ArgumentNullException. Call rejects references from another consumer with ArgumentException; stack validation still occurs at emission. A null literal passed to the overloaded Call requires a cast to the intended target type.

var dependency = AssemblyDefinition.ReadAssembly(dependencyPe, expectedExtended: false);
var method = dependency.MainModule.Types.Single(t => t.Name == "Math").Methods.Single();
var reference = output.ImportReference(method, dependencyCoreIdentity);
var main = output.AddFunction("Main");
main.LoadConstant(21);
main.Call(reference);
main.Return();
output.EntryPoint = main;
var nativeImage = output.WriteNativeAssembly();

Twenty-two C# contract groups now pass. They cover owned imports after producer/input mutation, exact PE method resolution, native global no-result calls, owner/core/identity rejections, opaque unsupported signatures and stack errors. The native C# gate imports its cross-assembly global from a PE snapshot and returns 42. The Raven consumer also imports from the read-only snapshot and returns 42 in neoCLR.

Native declaration reader and compiler reference projection

namespace NeoCLR.Metadata.Experimental.Model;
public sealed class NativeAssemblyDefinition
{
    public AssemblyIdentity Identity { get; }
    public IReadOnlyList<AssemblyIdentity> References { get; }
    public static NativeAssemblyDefinition ReadAssembly(ReadOnlySpan<byte> image);
    public byte[] CreateReferenceAssembly(AssemblyIdentity coreLibrary);
}

ReadAssembly copies an owned declaration snapshot from the bounded writer's native format-5 UTF-8 JSON. Identity retains the exact unsigned assembly identity. References retains exact direct native dependency identities in manifest order, including implementation-only references omitted from the PE projection. The list is owned and read-only; identities include version/culture/key/flags. It is bounded to 256 entries, performs no resolution or file/runtime loading, and is not a transitive closure. Hosts must supply the required native dependency graph to the runtime.

This is a metadata reader, not a native verifier, arbitrary format-5 reader, or body translator. Bodies remain opaque; the original native artifact must pass neoCLR's verifier before execution. Disposing JSON parsing state or changing the input buffer has no effect on the snapshot. No native file is loaded into a runtime by either API.

Supported declarations are public static Int32/Int64/Boolean/String/no-result functions (including globals) and public/internal static classes with no fields. The reader checks canonical identity tuples, encoded module/type/function names, references, origins, tokens, owner order, entry point signature, duplicate declarations and unsupported declaration fields. Unknown root/declaration fields and duplicate JSON properties are rejected. It accepts at most 4 MiB of input, depth 64, one manifest/module, 256 references, 4,095 types, 4096 methods, 256 methods per owner (including global scope), and 256 parameters per method. Unsupported, inconsistent or malformed metadata throws InvalidDataException. These consistency checks are not authentication and do not validate instruction bodies.

CreateReferenceAssembly creates owned PE bytes for the existing .NET semantic-loader bootstrap. coreLibrary is explicit and must supply System.Object and System.Runtime.CompilerServices.ReferenceAssemblyAttribute; null throws ArgumentNullException. The PE contains callable/type declarations, the reference-only attribute, and throwing placeholder bodies. Native bodies are never translated or replaced with executable behavior. Entry points and native body dependency references are omitted; this supported signature subset needs only primitive/core types. Exceeded writer limits or incompatible assembly identities throw InvalidDataException. Each projection can receive a fresh MVID; callers should reuse one projection/snapshot for a compilation instead of treating repeated projections as the same module scope.

var native = NativeAssemblyDefinition.ReadAssembly(nativeBytes);
var referencePe = native.CreateReferenceAssembly(explicitCoreIdentity);
var definitions = AssemblyDefinition.ReadAssembly(referencePe, expectedExtended: false);
// Register referencePe with the existing compiler loader and import definitions
// through AssemblyBuilder.ImportReference. Execute the original nativeBytes only.

This follows the .NET distinction between implementation and reference assemblies, including ReferenceAssemblyAttribute and throwing placeholder bodies. The temporary bridge adds a projection and cannot preserve arbitrary native semantics; a native semantic-data provider should replace it. See Microsoft's reference assembly contract.

Twenty-four C# contract groups pass, including native Unicode/global/no-result roundtrips, input ownership, malformed/unsupported metadata and count limits, reference marker inspection, and .NET execution-load rejection with BadImageFormatException. The Raven consumer starts from the native dependency, binds the projected declarations, and emits applications that neoCLR executes with the original dependency to 42.

Native reference tests additionally cover exact same-name/different-version identities, manifest order, repeated-call deduplication, collection immutability, source-buffer ownership, omission of implementation-only PE references, and inconsistent/duplicate native references. The compiler consumer now executes a three-assembly chain in neoCLR.

RuntimeAssemblyContainer

Development-only host type in NeoCLR.Metadata.Experimental:

public static class RuntimeAssemblyContainer
{
    public static byte[] Write(ReadOnlySpan<byte> nativeImage, AssemblyIdentity coreLibrary);
    public static byte[] WriteBinary(ReadOnlySpan<byte> nativeImage, AssemblyIdentity coreLibrary);
    public static byte[] Read(ReadOnlySpan<byte> image);
    public static AssemblyDefinition ReadCliProjection(ReadOnlySpan<byte> image);
}

Write accepts the bounded writer's native format-5 JSON and explicit core-library identity supplying Object and ReferenceAssemblyAttribute. It validates declarations, creates a reference-only CLI projection, then embeds a required NEOX execution section (kind 256, schema 1) in a new PE32 .neometa section. Both metadata views come from the same native snapshot. The native image plus its 32-byte envelope header/directory must fit 1 MiB; the PE must fit 4 MiB. Null core throws ArgumentNullException; unsupported declarations, exceeded bounds or malformed containers throw InvalidDataException. Each call creates a fresh projection MVID; whole-PE byte determinism is not promised.

Read validates unsigned PE32 framing, recognition marker/digest, envelope and native declarations. It returns an owned copy of native UTF-8 JSON; mutation cannot affect the input or future reads. Ordinary PEs, unknown required schemas, optional/unsupported execution sections, missing/changed bindings and malformed data throw InvalidDataException. Optional unknown sections are ignored. Bodies are opaque to this host API: successful inspection is not runtime admission, dependency resolution or typed verification.

ReadCliProjection performs the same checks and reads the physical CLI declarations as a Cecil-style AssemblyDefinition. Its Profile is null (no structural reference profile), EntryPointToken is zero and Write() preserves the complete original PE. It additionally rejects unsupported/malformed CLI metadata. The native payload is the runtime authority; this method does not prove semantic equality of arbitrary native and CLI views. Consumers should use the aware writer and keep their compiler-reference file and read snapshot identical. General rewriting and automatic resolution are absent.

byte[] native = builder.WriteNativeAssembly();
byte[] pe = RuntimeAssemblyContainer.Write(native, builder.CoreLibrary);
File.WriteAllBytes("Program.dll", pe);
var declarations = RuntimeAssemblyContainer.ReadCliProjection(pe);
var nativeDeclarations = NativeAssemblyDefinition.ReadAssembly(RuntimeAssemblyContainer.Read(pe));

neoCLR verify Program.dll / run Program.dll accepts this container, including --module Library.dll dependencies. The Rust host API is metadata_container::native_json(&[u8]) -> Result<&str, Fault> for borrowed transport extraction and metadata_container::load(&[u8]) -> Result<Module, Fault> for legacy validation, including bundled System linking. assembler::ModuleInput::MetadataPe(&[u8]) supports mixed explicit module sets; LoadedProgram remains responsible for linking and execution. There is no guest loader API yet. CLI bodies are throwing reference stubs, never executed by neoCLR. The payload still uses JSON; direct loading does not yet eliminate text parsing or establish a speedup. See the profile/design.

Native console literal output

MethodBuilder.WriteConsoleLine(string text) appends native console output without changing the surrounding Int32 stack. Text is limited to 64 KiB of valid UTF-8; null throws ArgumentNullException, unpaired UTF-16 surrogates and exceeded literal bounds throw ArgumentException. The assembly's aggregate console-literal bytes are limited to 4 MiB before serialization (InvalidDataException); encoded output/container limits still apply. WriteNativeAssembly lowers the operation to ldstr, System.Console.WriteLine(String) and pop for the bundled System's Void-valued result. System is the runtime's implicit platform dependency. CLI Write() rejects this native-only operation with InvalidDataException; reference-only projections preserve declarations and continue emitting throwing stubs. General string signatures and Console overload import are not introduced.

The compiled Raven acceptance case prints Hello World directly from Main, then from a separate Greet function called by Main. Both emitted containers load/verify/run in neoCLR and exit zero. The API remains independent of Raven; compiler-side mapping requires an explicit registered Console reference and only accepts string literals.

Binary execution payloads (schema 2)

public static byte[] RuntimeAssemblyContainer.WriteBinary(
    ReadOnlySpan<byte> nativeImage, AssemblyIdentity coreLibrary);

WriteBinary accepts the bounded writer's format-5 JSON (at most 4 MiB) as a host-side intermediate and writes section 256/schema 2 using a definite-length CBOR profile. The binary payload plus its 32-byte directory must fit 1 MiB; the PE still fits 4 MiB. It has the same core/reference projection, ownership and null-core contract as Write. InvalidDataException covers unsupported declarations, non-integer numbers, invalid encoding, duplicate fields and exceeded bounds. Only signed Int64 numbers, valid UTF-8 text, arrays, text-keyed maps, booleans and null are encoded; tags, bytes and floats are not part of this profile. Decode is limited to depth 64 and 262,144 items (including keys), and rejects duplicate keys, nonminimal encodings and trailing bytes.

Read and ReadCliProjection now accept schemas 1 and 2. For schema 1, Read returns the original JSON bytes; for schema 2 it reconstructs owned format-5 JSON with equivalent values for the existing host reader. Original whitespace/numeric spelling are not preserved. Reconstructed JSON remains bounded to 4 MiB. Snapshot Write still preserves the full original PE byte-for-byte. The writer continues to use fresh projection MVIDs. The original RuntimeAssemblyContainer.Write keeps emitting schema 1 for compatibility.

Rust metadata_container::decode(&[u8]) -> Result<Module, Fault> validates the container and decodes either payload without linking; load applies the legacy validation, including bundled System linking. Use ModuleInputMetadataPe for explicit dependency sets. Schema 2 is deserialized directly to the runtime model, with no JSON roundtrip. native_json remains a borrowed schema-1-only extractor and faults for schema 2. The CLI and ModuleInputMetadataPe use decode/load and accept both encodings. Binary containers have no embedded text for the debugger's source pane. See the binary profile and tradeoffs.

NativeModuleContainer

Public static host class in NeoCLR.Metadata.Experimental:

byte[] NativeModuleContainer.WriteBinary(ReadOnlySpan<byte> nativeImage);
byte[] NativeModuleContainer.Read(ReadOnlySpan<byte> image);
byte[] NativeModuleContainer.WriteLibraryBinary(ReadOnlySpan<byte> nativeImage);
byte[] NativeModuleContainer.WriteLibraryBinary(AssemblyBuilder assembly);

WriteBinary translates existing format-5 JSON values to a standalone NEOX envelope with required section 256/schema 2. Unlike RuntimeAssemblyContainer it does not require canonical API-writer declaration names and does not construct a PE or CLI projection. Read reconstructs equivalent owned JSON values. Neither call checks full declaration schemas, resolves references or verifies bodies; the runtime performs those checks. Header validation requires numeric format 5, nonempty module name and a functions array. Members, origins, identities, native names, dependencies and instruction operands are preserved as values. No tokens or references are remapped. Unknown optional envelope sections are accepted but omitted from the returned JSON; retain original bytes if opaque section preservation is required.

All calls throw InvalidDataException for malformed headers, framing, unsupported binary values or exceeded limits. WriteBinary retains schema 2: input JSON is limited to 4 MiB, the envelope to 1 MiB; the same integer-only, Unicode, depth and item limits as the PE binary profile apply. Lexical JSON spellings are not preserved. There is no CLI stream binding digest in this standalone form and no authenticity guarantee. It cannot be passed to Raven's .NET MetadataReference loader.

var image = NativeModuleContainer.WriteBinary(File.ReadAllBytes("System.neo.json"));
File.WriteAllBytes("System.neox", image);

Rust metadata_container::decode_envelope(&[u8]) -> Result<Module, Fault> accepts a standalone execution envelope (schema 1, 2 or 3), deserializes the native model and rejects invalid framing/required schemas. load_envelope additionally applies legacy validation, including bundled-System linking for non-System modules. ModuleInput::NativeEnvelope uses decode for explicit dependency sets. The CLI detects NEOX magic for the root, --module and --system; existing PE and JSON handling is unchanged. No embedded source text is available to the debugger.

WriteLibraryBinary emits required execution schema 3 in a standalone envelope. It accepts negative Int64 values and nonnegative UInt64 values; Double operands retain their exact unsigned IEEE-754 bits, including negative zero and NaN payloads. CBOR floating-point values themselves remain unsupported. Input/reconstructed JSON is limited to 32 MiB, the envelope to 8 MiB, and item count (including map keys) to 2,097,152. Depth remains 64. Read accepts schema 2 with its original limits and schema 3 with these larger budgets. The general MetadataEnvelope/MetadataSection public APIs retain their 1 MiB limits; the larger envelope is scoped to NativeModuleContainer. The PE RuntimeAssemblyContainer APIs continue to support schemas 1/2 only.

Older runtimes reject required schema 3; choose WriteBinary when the old profile's bounds and signed-only numbers suffice. The translator tool now emits schema 3 by default. This is an explicit compatibility change for that experimental tool, not a silent relaxation of schema 2. Semantic admission, linking and verification remain runtime responsibilities. Larger budgets increase possible memory/CPU costs; they are finite limits, not streaming or lazy-loading guarantees.

Rust host native assembly writer

metadata_container::write_module(module: &Module) -> Result<Vec<u8>, Fault> encodes an immutable borrowed native module into owned standalone schema-3 NEOX bytes. It serializes the model directly, without JSON, and preserves its definitions/references. Unsupported semantic format (anything except 5), empty/whitespace module name, encoding failures, payload/item/depth budget violations return Fault. The byte sink rejects output beyond 8 MiB minus envelope framing before extending its payload buffer; the completed encoding is checked by the same schema guard as the reader. It does not link dependencies, validate declarations or type-verify bodies. Callers perform those steps separately.

The CLI assemble --format neox uses the existing assembler/resolver and verifies the complete load set before invoking this API and creating the output file. Only the root module is serialized. This Rust-host function is not a new guest introspection API or an addition to the .NET Cecil-style object model. The independent .NET NativeModuleContainer reader validates the emitted wire format in the cross-reader consumer tests.

NativeLibraryDefinition and NativeFunctionDefinition

Development APIs in NeoCLR.Metadata.Experimental.Model. These .NET-host types are not guest Introspection APIs. They adapt native declarations to the existing Raven .NET semantic importer; they do not constitute a complete native symbol provider.

public sealed class NativeLibraryDefinition {
    public string ModuleName { get; }
    public IReadOnlyList<string> TypeNames { get; }
    public IReadOnlyList<NativeFunctionDefinition> Functions { get; }
    public static NativeLibraryDefinition ReadAssembly(ReadOnlySpan<byte> image);
    public byte[] CreateStaticInt32ReferenceAssembly(
        AssemblyIdentity projectionIdentity, AssemblyIdentity coreLibrary,
        IEnumerable<NativeFunctionDefinition> functions);
}
public sealed class NativeFunctionDefinition {
    public NativeLibraryDefinition Library { get; }
    public int TableIndex { get; }
    public string Name { get; }
    public string? DeclaringTypeName { get; }
    public bool TryGetStaticInt32Signature(out int parameterCount);
}
// Additional MethodBuilder overload:
public void Call(NativeFunctionDefinition target);

ReadAssembly accepts standalone binary schemas 2/3 through NativeModuleContainer, including the translated System library. It owns the decoded data and inventories all functions, even unsupported signatures. ModuleName and Name retain native spellings; TypeNames retains table order and can repeat for differing generic arities. Duplicate name/arity types fail. Inventories are limited to 65,536 types/functions, descriptive names to 4,096 characters, and transport retains its existing byte/depth/item limits. Malformed framing/inventory raises InvalidDataException. This is not runtime body or complete declaration validation. TableIndex is snapshot-local position, not an inferred CLI token or persistent native identity. DeclaringTypeName is a nominal Named owner; null also covers generic/primitive owner forms that this callable view does not support.

TryGetStaticInt32Signature accepts static nongeneric nominal-owner functions with 0–256 Int32 parameters and an Int32 result. Private, instance, virtual, abstract, byref-receiver, no-result, Result, generic and other signatures return false and count zero. Native visibility defaults to public when omitted; explicit nonpublic visibility or nonpublic origin access is rejected. It does not promise the owning type is projectable; the projection separately checks owner existence, public visibility and nongeneric shape.

The projection requires an explicit partial selection of 1–4096 owned function objects and an unsigned synthetic identity distinct from the supplied core identity. At most 256 distinct owners are projected. Empty, duplicate, foreign or unsupported selections, duplicate signatures and invalid owners fail with InvalidDataException. Null arguments fail with ArgumentNullException. The returned ordinary reference-only PE preserves selected method names and Int32 signatures under original type names, using static containers and throwing bodies. It does not preserve native assembly identity, type instance/field/property shape, generic contracts, parameter names or attributes. No methods outside the explicit selection are claimed to be available. Treating the projection as a complete core library or as an executable implementation is unsupported. Native/native-host type-name collisions still require a proper core provider; the current command removes host facade references in selected-native mode and the consumer verifies that Math.Min binds to the native view, not the host implementation.

MethodBuilder.Call(NativeFunctionDefinition) accepts only a recognized Int32 callable from module System; null raises ArgumentNullException, other modules or signatures raise InvalidDataException. The native writer retains the original owner, function name and parameter signature; it does not synthesize writer-specific hashed identities for System methods. Stack underflow is rejected during writing. Ordinary CLI writing rejects this native-only operation. Runtime verification and execution must use the matching explicit System assembly. No revision or image digest is encoded for that implicit System dependency; this is a bootstrap limit to replace with a general native assembly binding contract.

Compiled examples and failures: NativeLibrarySymbolChecks.cs in the metadata C# tests and Raven's SystemSymbolChecks.cs consumer. The builder provides the bounded opcode/operand Emit API below. An editable instruction collection and full Cecil body-editing support remain future work.

OpCode and MethodBuilder.Emit

Development APIs in NeoCLR.Metadata.Experimental.Model. The enum describes logical instructions supported by both writer backends; its numeric values are not physical CLI or native opcode bytes.

public enum OpCode { Ldc_I4, Ldarg, Add, Sub, Mul, Call, Ret, Ldloc, Stloc, Ceq, Clt, Cgt, Br, Brtrue, Brfalse, Ldc_Bool, Pop, Ldc_I8, Conv_I8, Conv_I4, Neg, Not, Ldstr, Starg, Div, Rem, And, Or, Xor, Shl, Shr }
public sealed partial class MethodBuilder {
    public void Emit(OpCode opCode);
    public void Emit(OpCode opCode, int operand);
    public void Emit(OpCode opCode, MethodBuilder operand);
    public void Emit(OpCode opCode, ImportedMethodReference operand);
    public void Emit(OpCode opCode, NativeFunctionDefinition operand);
}
Opcode Operand Contract
Ldc_I4 int Push a signed Int32 constant.
Pop none Discard one value of either supported primitive type; empty stack rejects when writing.
Ldarg int Load the zero-based declared primitive argument; bounds checked when writing.
Add, Sub, Mul, Div, Rem none Consume matching Int32/Int64 values and push the same-width arithmetic result.
Call MethodBuilder Use the target signature; external core/identity constraints checked when writing.
Call ImportedMethodReference Must belong to the consuming assembly builder.
Call NativeFunctionDefinition Native-only static Int32 System callable; matching System must be supplied at runtime.
Ret none Must finish the body with its exact declared return stack.

Unknown enum values, missing/unexpected operands and wrong opcode/operand overloads raise ArgumentException before appending. Null call operands raise ArgumentNullException; foreign imported references raise ArgumentException. Unsupported native module/signature raises InvalidDataException, as does exceeding the existing 4096-instruction method limit. Failed Emit calls leave the body unchanged. Stack/argument/return validation remains at Write/WriteNativeAssembly; raw emission does not bypass it. Ordinary CLI writing still rejects native System calls. No caller-supplied object, byte array or metadata token operand is accepted.

LoadConstant, LoadArgument, Add, Subtract, Multiply, all Call overloads and Return now call Emit. Their supported semantics are unchanged. WriteConsoleLine remains a native convenience expansion; general string operands, non-primitive local variables, exception regions and editable instruction collections are unsupported. Future ILProcessor-like editing must define instruction ownership and branch/exception target repair separately.

Example from the C# consumer, used with an Int32 method and a two-parameter Int32 helper:

main.Emit(OpCode.Ldc_I4, 10);
main.Emit(OpCode.Ldc_I4, 4);
main.Emit(OpCode.Call, helper);
main.Emit(OpCode.Ret);

EmitChecks.cs proves helper/raw byte equivalence on the same graph, executes a CLI arithmetic/call entry point to 42, and checks imported/native operands and failures. Raven's native emitter uses this surface; native runtime and translated-System integration remain its executable consumer evidence.

Int32 local slots

The host-only NeoCLR.Metadata.Experimental.Model API adds:

public sealed class LocalDefinition {
    public MethodBuilder Method { get; }
    public int Index { get; }
}
public sealed partial class MethodBuilder {
    public IReadOnlyList<LocalDefinition> Locals { get; }
    public LocalDefinition DeclareInt32Local();
    public void LoadLocal(LocalDefinition local);
    public void StoreLocal(LocalDefinition local);
    public void Emit(OpCode opCode, LocalDefinition local);
}

DeclareInt32Local allocates a stable zero-based slot, at most 256 per method; exceeding that bound throws InvalidDataException. Locals is a read-only ordered view. ClearBody clears instructions and retains locals/handles; rebuilding the method is required to discard its declarations. The typed Emit overload accepts only Ldloc and Stloc. Null throws ArgumentNullException, a different method owner or incorrect opcode throws ArgumentException, and the existing instruction bound throws InvalidDataException. Rejected instructions do not alter the body.

The existing Emit(OpCode, int) overload also accepts raw Ldloc/Stloc slot indices. Writes reject out-of-range slots, stack underflow and loads before a store in the linear body with InvalidDataException. Each write recomputes initialization; a previous body or successful write does not initialize a rebuilt body. CLI emission writes Int32 local signatures and init-locals method headers; native emission writes format-5 locals and native local instructions. The reader accepts absent locals in older producer artifacts and validates declared Int32/Int64/Boolean/String local lists; reference projections still omit executable body details. Older experimental readers may reject the added locals field.

Unlike unrestricted Cecil bodies, this bounded API enforces initialization and stack contracts when writing. Typed owner handles prevent accidental cross-method use; raw indices support assembler consumers. General local types, address-taking and scope/debug metadata remain outside this slice. The compiled C# LocalChecks consumer executes CLI locals and checks native roundtrips and rejected contracts; Raven's local assignment probe additionally verifies and executes the binary artifact in neoCLR.

Branch labels and control flow

public sealed class BranchLabel { public MethodBuilder Method { get; } }
public sealed partial class MethodBuilder {
    public BranchLabel DefineLabel();
    public void MarkLabel(BranchLabel label);
    public void Emit(OpCode opCode, BranchLabel label);
    public void Emit(OpCode opCode, bool operand);
}

DefineLabel allocates a method-owned symbolic destination (maximum 4096; InvalidDataException beyond that). MarkLabel marks its current position once. The label Emit overload accepts Br, Brtrue and Brfalse; the Boolean overload accepts only Ldc_Bool. Null labels throw ArgumentNullException; wrong owners, repeated marks and incompatible opcodes throw ArgumentException without changing instructions. Instruction-limit violations throw InvalidDataException. ClearBody retains handles but removes marks, so reused destinations must be marked again.

Operand-free Ceq pops two matching Int32, Int64 or Boolean values and pushes Boolean; mixed operand types reject. Clt and Cgt pop matching Int32/Int64 values and push Boolean, using signed comparisons. Boolean equality permits logical negation (false; ceq) without treating native Boolean as Int32. Conditional branches pop Boolean, not Int32; conditions may also use Ldc_Bool. General Boolean locals/signatures are not introduced here.

Writing computes typed stack states and definitely stored locals over the control-flow graph, including backward edges. Unmarked targets, incompatible stack joins, wrong operand types, uninitialized loads on any incoming path, reachable fallthrough and unreachable executable instructions fail with InvalidDataException. Return instructions may occur on multiple reachable paths, each with the declared result and no extra stack values. Labels emit no runtime instruction. Unused/unreachable label marks are harmless. The earlier linear-only validation contract is superseded for branch-capable bodies.

CLI destinations become byte displacements; native destinations become instruction indices after convenience-operation expansion (including Console output). Labels do not encode byte offsets themselves, so backend layouts remain independent. The native runtime already supports these format-5 instructions; no binary schema changes are needed. Compared with Cecil's general ILProcessor, this supports forward/backward branches with owned labels and checked typed control flow, but still has no insertion/removal API, exception regions or arbitrary opcode surface. C# FlowChecks covers executable loops and invalid joins/initialization; Raven's executable consumer includes Console inside a loop.

Primitive signatures

All types below are in NeoCLR.Metadata.Experimental.Model.

public enum PrimitiveType { Void, Int32, Boolean, Int64, String, Byte, Single, Double }
public sealed class PrimitiveMethodSignature
{
    public PrimitiveMethodSignature(PrimitiveType returnType,
                                    IEnumerable<PrimitiveType> parameterTypes);
    public PrimitiveType ReturnType { get; }
    public IReadOnlyList<PrimitiveType> ParameterTypes { get; }
}
MethodBuilder AssemblyBuilder.AddFunction(string name, MethodSignature signature);
MethodBuilder TypeBuilder.AddMethod(string name, MethodSignature signature);
MethodSignature MethodBuilder.Signature { get; }
MethodSignature ImportedMethodReference.Signature { get; }
bool MethodDefinition.TryGetStaticPrimitiveSignature(out PrimitiveMethodSignature? decoded);

The signature constructor copies up to 256 ordered Int32/Int64/Boolean/String parameters. Results may also be Void, meaning no result, not an inhabited native Void value. Null parameters throw ArgumentNullException; invalid enum values, Void parameters or excessive counts throw ArgumentException. ParameterTypes is an immutable view of the copied array.

The typed declaration overloads retain existing name/owner/count bounds. A null signature throws ArgumentNullException; duplicate name plus ordered parameter types throws ArgumentException, regardless of result type. Thus Identity(int) and Identity(bool) coexist, while return-only overloads reject. Legacy count/result overloads still mean Int32 parameters and Int32/no-result return.

MethodBuilder.Signature and ImportedMethodReference.Signature expose the immutable contract. ParameterCount includes both types; ReturnsValue includes Boolean. Calls consume declared parameter types in reverse stack order, and Return checks the declared result. Int32 is not implicitly interchangeable with Boolean. Entrypoints remain parameterless Int32/no-result; Boolean entrypoints reject at write time.

The primitive recognizer returns a fresh signature on success or null/false for unsupported or malformed encodings. It accepts only static nongeneric default CLI calling convention, canonical parameter counts and exact primitive encodings. TryGetStaticInt32Signature keeps its earlier stricter behavior and rejects Boolean. MemberReference.ResolveMethod and AssemblyBuilder.ImportReference match full primitive/vector signatures, including ordered parameter types and result. Existing explicit resolver, identity, core-contract and snapshot checks remain in force.

Native writers, readers and reference-only projections preserve these types without a format/schema change. Older experimental readers may reject Boolean declarations. Local declarations support Int32 and Boolean; selected System inventory imports remain the separate Int32-only contract. Native bodies are still verified by neoCLR.

var predicate = output.AddFunction("IsPositive",
    new PrimitiveMethodSignature(PrimitiveType.Boolean, [PrimitiveType.Int32]));
predicate.LoadArgument(0);
predicate.LoadConstant(0);
predicate.Emit(OpCode.Cgt);
predicate.Return();

C# contract tests cover mixed arguments, overloads, CLI execution, native projection, MemberRef resolution, immutable signatures and invalid calls. Raven's integration probe also executes the emitted Boolean calls in neoCLR, including a separately compiled library referenced through its CLI declaration projection.

Typed local declarations

LocalDefinition MethodBuilder.DeclareLocal(PrimitiveType type);
PrimitiveType LocalDefinition.Type { get; }

DeclareLocal accepts Int32, Int64, Boolean or String, returning a stable method-owned slot with an immutable Type. Void and unknown enum values throw ArgumentException; the shared 256-local limit throws InvalidDataException. DeclareInt32Local remains shorthand for DeclareLocal(PrimitiveType.Int32). ClearBody preserves the slot and type, but resets body-derived initialization: a load must follow stores on all reachable paths.

StoreLocal and raw Stloc require the value's type to match the slot, including Boolean; LoadLocal/Ldloc push that type. Wrong types reject before either writer emits an image. CLI local signatures and native local lists retain the type. Native declaration reading accepts both primitive local types, including old artifacts with no local-list field. Reference-only projections omit native executable bodies and locals as before.

The C# local contracts execute Boolean locals in CLI, inspect their reflected type, roundtrip native projections and reject cross-type stores and uninitialized loads. Raven's shared planner now carries local types to each backend and validates a program that stores a predicate result, reassigns it and compares Boolean locals on both runtimes.

Discarding call results

MethodBuilder.Emit(OpCode.Pop) removes one evaluation-stack value, preserving all values below it. It accepts no operand and works for Int32, Int64, Boolean or String. Emission with an operand throws ArgumentException without appending an instruction. Writer flow validation throws InvalidDataException on underflow, including popping after a no-result call. A no-result call has no value to discard. CLI emission uses pop; native emission uses neoIL pop, with no schema change. Existing limits and branch join checks continue to apply. Tests execute discarded Boolean and Int32 calls in CLI and verify native writer rejection of underflow; Raven's binary-assembly consumer also executes local and imported statement calls in neoCLR.

Int64 and integer conversions

The primitive signature/local API also accepts PrimitiveType.Int64 in parameters, results and local slots. MethodDefinition.TryGetStaticPrimitiveSignature, typed imports, MemberRef resolution, native reading and reference-only projections preserve Int64. The legacy Int32 recognizer still rejects every Int64 signature. Entrypoints remain parameterless Int32/no-result; Int64 entrypoints reject before writing.

void MethodBuilder.Emit(OpCode opCode, long operand); // Ldc_I8 only
// Operand-free Emit also accepts Conv_I8 and Conv_I4.

Ldc_I8 carries the exact signed 64-bit operand, including both extrema. Other opcodes on this overload throw ArgumentException; instruction limits throw InvalidDataException. Pass a long operand (42L), since the int overload continues to recognize only its existing operands. No implicit opcode/operand widening is performed.

Conv_I8 accepts Int32/Int64, sign-extending Int32; Conv_I4 accepts the same types and retains the low 32 bits when narrowing. Both operations are unchecked. Boolean and empty-stack conversions reject at write time with InvalidDataException. Add/Sub/Mul and signed Clt/Cgt accept matching Int32 or Int64 operands; Ceq additionally accepts matching Boolean. Arithmetic preserves width, comparisons produce Boolean. There is no implicit mixed-width arithmetic or Boolean/integer interchange. Pop also discards Int64 values. Typed calls, returns, local stores and branch joins preserve exact types.

CLI emission uses Int64 signatures, ldc.i8 and conv.i4/conv.i8. Native emission uses the corresponding existing neoIL operations and Int64 type names, without a schema change. Older experimental host readers may reject these newly admitted declarations. Checked and user-defined conversions remain unsupported. See the floating-point profile below for Single/Double conversions. Native verification is still required before execution.

C# tests cover extrema, sign extension, truncation, local types, native projection, imports, strict legacy recognition and invalid conversions/mixed arithmetic. Raven's consumer executes long locals and signed conversion boundaries in neoCLR and imports an Int64 callable from a separately compiled binary library.

Signed unary integer operations

MethodBuilder.Emit(OpCode.Neg) negates the top Int32/Int64 value without changing its width. Negating the minimum signed value wraps to that same value, matching the CLI neg operation. Emit(OpCode.Not) complements every bit at the operand's width; it is not Boolean logical negation. Neither opcode accepts an operand: other Emit overloads reject with ArgumentException without appending an instruction. Existing instruction bounds throw InvalidDataException.

Both writers reject empty stacks and Boolean operands with InvalidDataException during flow validation. CLI emission uses neg/not; native emission uses the existing neoIL neg/not operations without a format change. Checked and unsigned unary support is not implied; the floating-point profile below also admits Single/Double negation. Native verification remains required. C# contracts check both widths, extrema, invalid stack operands and native projections. Raven's shared body path handles built-in signed unary + (identity), - and ~; the native consumer executes minimum-value wrapping and complements in binary assemblies.

String values

// NeoCLR.Metadata.Experimental.Model
// PrimitiveType.String and OpCode.Ldstr are appended enum members.
void MethodBuilder.Emit(OpCode opCode, string operand);
void MethodBuilder.WriteConsoleLine();

String is supported in PrimitiveMethodSignature parameters/results, DeclareLocal, MethodDefinition.TryGetStaticPrimitiveSignature, imported method references and native reference projections. It is a built-in text contract, not general nominal type support. The legacy Int32 recognizer still rejects String; String entrypoints are invalid.

Emit(Ldstr, text) pushes a string. Text may be empty and contain embedded NUL or supplementary Unicode characters; it must be non-null, valid Unicode and at most 65,536 UTF-8 bytes. Null throws ArgumentNullException; an incorrect opcode, unpaired UTF-16 surrogate or oversized literal throws ArgumentException without appending an instruction. The assembly-wide string/instruction/image limits still apply. The CLI writer uses a user-string token and native output uses UTF-8 text with ldstr.

WriteConsoleLine() consumes one String value through the existing native System console bootstrap and discards its inhabited Void result. It is native-only; CLI Write rejects it. Stack mismatch/underflow fail at write time with InvalidDataException. The existing string-argument overload remains a constant-output convenience.

String calls, returns, local stores, loads, Pop and control-flow joins retain exact type checks. Arithmetic, numeric conversions, Ceq/Clt/Cgt and conditional branches do not accept String. Null literals, string equality/concatenation and String instance members are outside this bounded writer API; no interning/identity guarantee is made.

The C# StringChecks consumer covers CLI execution, native projection and imports, Unicode/empty/NUL literals, exact UTF-8 bounds and rejected operations. Raven's native probe additionally executes computed Unicode text and a separately compiled library.

Argument stores

// NeoCLR.Metadata.Experimental.Model
void MethodBuilder.StoreArgument(int index);
void MethodBuilder.Emit(OpCode opCode, int operand); // now also accepts Starg

Starg consumes a value of the parameter's exact declared Int32/Int64/Boolean/String type and replaces that by-value argument slot in the current invocation. StoreArgument is a convenience for the same instruction. Parameters begin initialized; subsequent Ldarg observes the replacement. Caller storage is not changed. Indices are zero-based with no implicit receiver, bounded by the method signature (at most 256 parameters).

Invalid indices, including negative values, are rejected at writing even in unreachable code. Stack underflow and mismatched stored types throw InvalidDataException before bytes are returned. The general instruction limit applies at emission. The int Emit overload retains its existing opcode/operand validation; Starg with other operand kinds rejects with ArgumentException.

CLI output uses standard starg (FE 0B plus UInt16 slot); native output uses existing format-5 starg. No signature or container schema changes are required. Mutability is a source binding rule, not additional parameter metadata. Ref/out/in and receiver assignment are outside this bounded API. C# contracts cover all four admitted types, caller isolation, the last slot, bounds, empty stack and type mismatch.

Signed division (development 2026-10-01)

OpCode.Div and void MethodBuilder.Divide() append operand-free signed integer division. Emit(OpCode.Div) is equivalent to the helper. Writing requires two matching Int32 or Int64 values and leaves one value of that width; stack underflow, mixed widths, Boolean and String operands raise InvalidDataException before an image is returned. Operand-bearing Emit overloads reject Div with ArgumentException. The new enum member is appended; numeric enum values are not serialized opcodes.

Both CLI div and native div truncate toward zero. Dividing by zero or the minimum signed value by -1 is legal to emit but faults when executed (CLR arithmetic exceptions; neoCLR DivideByZero/ArithmeticOverflow faults). Neither helper performs constant evaluation. No unsigned, floating or checked-context overload is provided. Existing signature metadata and native transport are unchanged.

Signed remainder (development 2026-10-01)

OpCode.Rem and void MethodBuilder.Remainder() append operand-free signed remainder; Emit(OpCode.Rem) is equivalent. The typed stack rules and failures match Div: two matching Int32/Int64 operands become one value of the same width. Invalid stacks raise InvalidDataException when writing; operand-bearing overloads reject Rem with ArgumentException. Rem is appended to the enum without renumbering previous members.

Ordinary nonzero results have the dividend's sign and smaller magnitude than the divisor. Both writers use existing rem instructions. Zero divisors fault at execution; neoCLR also faults on minimum/-1. CLI output follows the host CLR's rem behavior (the tested host faults for minimum/-1 too; .NET documents this edge as platform sensitive). No unsigned/floating remainder or new exception handling is added.

Integer and Boolean bitwise operations (development 2026-10-01)

OpCode.And, Or, Xor and the operand-free MethodBuilder.BitwiseAnd(), BitwiseOr(), BitwiseXor() helpers consume two matching Int32/Int64 or Boolean values and produce the same type. Boolean operands use eager AND/OR/XOR truth tables; these instructions do not short-circuit. Emit(opCode) is equivalent to the corresponding helper. Sign bits participate normally; these operations do not overflow. CLI and native output use existing and/or/xor instructions, with no metadata extension.

Writing rejects underflow, mixed types/widths or String operands with InvalidDataException. Operand-bearing Emit overloads reject these opcodes with ArgumentException; the instruction limit still applies. New enum values are appended. Enum and nullable Boolean semantics are not added. Native Boolean operands require the runtime Boolean bit-operation support introduced on codex/extended-cli-metadata in fa25609d; older runtimes reject them. CLI keeps ordinary and/or/xor encoding.

Integer shifts (development 2026-10-01)

OpCode.Shl/Shr and void MethodBuilder.ShiftLeft()/ShiftRight() consume an Int32 count above an Int32 or Int64 value and leave a result with the value's width. Emit(opCode) is equivalent. Left shifts discard high bits; signed right shifts replicate the sign bit. No unsigned shift is included. Counts are stack values, not Emit operands. Operand-bearing overloads reject Shl/Shr with ArgumentException. Writing rejects missing operands, an Int64 count or a Boolean/String value with InvalidDataException; count values are not range-checked by the writer.

These map directly to standard CLI/native shl/shr. For counts 0–31 or 0–63 respectively, results agree. CLI results for negative/oversized counts are unspecified; native execution keeps its existing count masking (low 5 or 6 bits). Callers needing portable masked semantics can emit an explicit AND on the count before shifting. The API does not insert that policy or change ordinary .NET codegen. The enum values are appended.

MethodVisibility (development 2026-10-01)

public enum MethodVisibility { Public, Internal, Private }
public MethodBuilder TypeBuilder.AddMethod(string name,
    MethodSignature signature, MethodVisibility visibility);
public MethodVisibility MethodBuilder.Visibility { get; }

The overload creates a static method with explicit access; existing AddMethod overloads remain public. Public is subject to owner visibility, Internal restricts access to the assembly, and Private to the declaring type. Invalid enum values raise ArgumentOutOfRangeException; null signatures raise ArgumentNullException; name, duplicate-signature and method-count rules are unchanged. Visibility is immutable. Assembly functions retain public metadata representation; protected/friend access is not added. MethodDefinition.Attributes already exposes the corresponding CLI bits.

CLI output uses standard Public/Assembly/Private MethodAttributes. Native output reuses public/internal/private visibility and matching origin member_access (Internal maps to Assembly). Public rows keep the omitted visibility default. The bounded native reader accepts old public rows, validates access/origin consistency and preserves all three values in the reference projection. It rejects unknown access, inconsistent flags and nonpublic global functions with InvalidDataException. Older readers reject new nonpublic rows. Bodies/references can describe forbidden calls: the writer is not an access checker; Raven binding and runtime verification enforce access. ImportReference retains that rule.

Assembly function access (development 2026-10-01)

AssemblyBuilder.AddFunction(string name, MethodSignature signature, MethodVisibility visibility) creates an ownerless function with Public or Internal access. Existing overloads remain Public. Name/signature bounds and duplicate checks are unchanged. A null signature raises ArgumentNullException; invalid names, duplicate signatures or exceeded limits raise ArgumentException. Private/unknown visibility raises ArgumentOutOfRangeException before graph mutation: private access requires a declaring type in the current native access model.

MethodBuilder.Visibility retains the selected access. CLI globals use ordinary Public/Assembly MethodAttributes; native functions retain no owner and use existing public/internal visibility. The bounded native reader preserves internal function access in its CLI reference projection and rejects private ownerless definitions. Older bounded readers reject internal global rows; no schema version changes. The writer does not authorize calls; native verification checks resolved module identity. Explicit entry selection may run an internal function in its defining module.

Assembly function namespaces

Development host APIs (2026-10-01):

MethodBuilder AssemblyBuilder.AddFunction(string @namespace, string name,
    MethodSignature signature, MethodVisibility visibility = MethodVisibility.Public);
string MethodBuilder.Namespace { get; }

Adds an assembly-owned function with no declaring type. The namespace is empty for the global namespace; otherwise it consists of nonblank dot-separated segments, valid Unicode, and no control characters. Combined namespace/name length is at most 1024 UTF-16 code units. Duplicate namespace/name/parameter-type signatures and more than 256 assembly functions are rejected. Null namespace/signature throws ArgumentNullException; invalid namespace/name/duplicate/limit throws ArgumentException; unsupported visibility throws ArgumentOutOfRangeException. Rejection leaves the graph unchanged. Existing AddFunction overloads use the empty namespace.

MethodBuilder.Namespace returns the declared function namespace or type-owner namespace. Name remains the simple source name. ImportedMethodReference.Namespace now also exposes a namespaced function's namespace (null for global-namespace functions); DeclaringTypeName remains null for all ownerless functions.

Native metadata stores the namespace separately and includes it in the executable name encoding. The temporary CLI projection uses global MethodDefs named <NeoFunction>{uppercase UTF8 namespace hex}_{uppercase UTF8 name hex}. The prefix is reserved by AddFunction even in the global namespace to avoid collisions. Existing unnamespaced function encoding is unchanged. Native snapshot/reference creation and ImportReference preserve the namespace through that encoding. Raw CLI snapshots expose the encoded physical Name; ordinary .NET source loaders do not gain native assembly-level-function lookup. Native bodies remain authoritative in PE/#Neo artifacts.

var min = assembly.AddFunction("System.Math", "Min",
    new PrimitiveMethodSignature(PrimitiveType.Int32,
        new[] { PrimitiveType.Int32, PrimitiveType.Int32 }));
// min.Namespace == "System.Math"; min.DeclaringType == null

The native reader rejects inconsistent namespace/executable names and namespaces on type-owned methods. The runtime retains the namespace and rejects malformed or type-owned namespace annotations. Calls use exact executable names; source namespace lookup belongs to the compiler. New output requires the matching reader/runtime; older artifacts omit the field and retain their global-namespace behavior.

Root classes and primitive instance fields

Development host API (2026-10-01), additional to existing static AddType:

TypeBuilder AssemblyBuilder.AddClass(string @namespace, string name,
    TypeVisibility visibility = TypeVisibility.Public);
bool TypeBuilder.IsStatic { get; }
IReadOnlyList<FieldBuilder> TypeBuilder.Fields { get; }
FieldBuilder TypeBuilder.AddField(string name, SignatureType type,
    FieldVisibility visibility = FieldVisibility.Private, bool isReadOnly = false);
public enum FieldVisibility { Public, Internal, Private }

AddClass creates a nonabstract, nonsealed root reference class. CLI base is System.Object; native metadata has no explicit base. No constructor is synthesized. AddType continues to create static classes. Both share the 4,095-type limit and namespace/name uniqueness. Invalid names/visibility/duplicates throw ArgumentException (including ArgumentOutOfRangeException for visibility). Namespaces and type names retain the existing AddType contract.

AddField declares instance storage, never a property; storage is mutable by default. It accepts Int32, Int64, Boolean, String or an owned nonstatic root class, a unique nonblank name without controls or invalid Unicode, up to 1024 characters, and defined FieldVisibility values. Invalid declarations or more than 256 fields per type throw ArgumentException before mutation. Static owners throw InvalidOperationException. Writing enforces at most 4096 assembly fields. Literal and static fields remain unsupported here. Later generic and imported reference-type field support uses the signature contracts documented below. Null types throw ArgumentNullException; Void and foreign classes throw ArgumentException before mutation. Forward and self references use exact output-builder identity. FieldBuilder exposes read-only DeclaringType (TypeBuilder), Name (string), FieldType (SignatureType), Visibility (FieldVisibility) and IsReadOnly (bool). Field handles are owned by their type. Development API migration: rebuild consumers and inspect FieldType.Primitive or FieldType.ClassType; primitive AddField calls continue through implicit conversion. CLI fields use ordinary CLASS TypeDef signatures; native fields use existing Named records, preserved by reference projection. This introduces no new binary schema. Setting isReadOnly emits ordinary CLI InitOnly and the existing native field_readonly flag. Executable writes fail with InvalidDataException when an ordinary method or a constructor of another type stores the field. Declaration/reference projection preserves these flags. The updated runtime enforces direct stores and returns readonly managed field addresses outside the declaring constructor; reads and mutation of an object referenced by a readonly field remain legal. This is shallow storage protection, not deep immutability or an unsafe-memory sandbox. Raw unmanaged pointers remain outside managed readonly guarantees. Constructors can acquire writable initialization references. Development migration: rebuild AddField consumers for the added optional argument and use the matching runtime; older runtimes do not enforce these flags during execution. No new binary schema is introduced by this bridge extension.

Nominal stores require the exact declared class; null literals, nullable source contracts and external class imports are not added by this slice.

Read-only snapshot additions:

uint TypeDefinition.Attributes { get; } // physical TypeAttributes
IReadOnlyList<FieldDefinition> TypeDefinition.Fields { get; }
IReadOnlyList<FieldDefinition> ModuleDefinition.Fields { get; }
FieldDefinition? ModuleDefinition.GetFieldDefinition(uint metadataToken);

Fields are ordered physical Field rows, with at most 4096 rows and aggregate signature bytes bounded by the reader's existing 4 MiB limit. GetFieldDefinition returns null for absent/wrong-kind tokens. FieldDefinition exposes Module, MetadataToken, DeclaringType, Name and ushort Attributes (FieldAttributes). GetSignature() returns a new byte array; unsupported encodings remain opaque. TryGetPrimitiveType(out PrimitiveType type) recognizes exact Int32/Int64/Boolean/ String field signatures, returning false and Void otherwise. No resolution or code loading occurs. CLI global fields retain the physical module pseudo-type as owner.

var order = assembly.AddClass("Example", "Order");
var number = order.AddField("Number", PrimitiveType.Int32);
var pending = order.AddField("Pending", PrimitiveType.Boolean, FieldVisibility.Internal);

Native/reference projection preserves class flags, field order/types/access and module-scoped Field tokens in origin metadata. The bounded native reader rejects unsupported shapes and inconsistent origin rows. Old readers cannot read new class/ field output. Construction and field instructions are described below.

Root construction and instance bodies

Development host API (2026-10-01):

MethodBuilder TypeBuilder.AddInstanceMethod(string name, MethodSignature signature,
    MethodVisibility visibility = MethodVisibility.Public);
MethodBuilder TypeBuilder.AddConstructor(IEnumerable<PrimitiveType> parameterTypes,
    MethodVisibility visibility = MethodVisibility.Public);
bool MethodBuilder.IsStatic { get; }
bool MethodBuilder.IsConstructor { get; }
void MethodBuilder.Duplicate();
void MethodBuilder.NewObject(MethodBuilder constructor);
void MethodBuilder.LoadField(FieldBuilder field);
void MethodBuilder.StoreField(FieldBuilder field);
void MethodBuilder.Emit(OpCode opcode, FieldBuilder field);
// Added enum values: Dup, Newobj, Ldfld, Stfld.

AddInstanceMethod creates a nonvirtual method on a root class. AddConstructor creates an instance .ctor with Void result. Signatures contain only declared primitive parameters (maximum 256), excluding the receiver. Argument slot zero holds the exact declaring-class receiver; declared parameters start at one. Static methods keep their existing indexing. LoadArgument supports both kinds; StoreArgument rejects receiver stores when writing. Entry points must be static. Names .ctor/.cctor are reserved in ordinary AddMethod/AddInstanceMethod; use AddConstructor. Null signatures/parameter sequences throw ArgumentNullException. Invalid names, access values, duplicate name/parameter signatures or limits throw ArgumentException; static owners reject instance declarations with InvalidOperationException before mutation.

Emit(Dup) and Duplicate copy the top stack value, preserving reference identity. Emit(Newobj, constructor) and NewObject consume declared constructor arguments and push an owned class reference. Emit(Call, method) and Call consume declared parameters and, for instance methods, the receiver below them. Direct Call to a constructor and Newobj to an ordinary method throw ArgumentException. Builder method references retain the existing external assembly identity/core contract; imported snapshot references remain static-only.

Emit(Ldfld, field)/LoadField consume the exact declaring-class receiver and push the primitive or owned nominal field value. Emit(Stfld, field)/StoreField consume receiver then value. Field handles must belong to the output assembly; foreign fields/wrong opcodes throw ArgumentException and null operands throw ArgumentNullException before mutation. Writing rejects stores to readonly fields outside a declaring constructor, stack underflow, mismatched receivers/values/joins and receiver stores with InvalidDataException; existing instruction/body bounds apply. Access control remains enforced by the executing target, not a new writer-level access checker.

CLI output uses ordinary HasThis signatures, constructor flags, newobj/dup/ldfld/stfld and Field tokens. A root constructor's CLI body receives an automatic six-byte ldarg.0/call System.Object::.ctor prologue; branches target the declared body, never re-run that prologue. Native roots need no base call, and use the existing instance, newobj.ctor and field-slot contracts. This is an explicit backend initialization contract, not arbitrary identical IL bodies or general constructor chaining. Reference projections preserve instance signatures and constructor flags with throwing bodies; executable native bodies still reside in the required #Neo payload.

No constructor is synthesized. External inheritance, virtual dispatch, arbitrary constructor chaining, indexed properties and external instance snapshot imports remain outside this bounded producer. Owned nominal parameters/results/locals, fields and properties are supported. The C# fixture constructs an Order, mutates it through one alias and reads through another; both targets return 42. The separate Raven Order integration now compiles the unchanged declaration; see the bridge evidence.

Primitive property associations

Development host API (2026-10-01):

IReadOnlyList<PropertyBuilder> TypeBuilder.Properties { get; }
PropertyBuilder TypeBuilder.AddProperty(string name, SignatureType type,
    MethodBuilder? getter = null, MethodBuilder? setter = null);

PropertyBuilder exposes DeclaringType (TypeBuilder), Name (string), PropertyType (SignatureType), GetMethod/SetMethod (nullable MethodBuilder), and IsStatic (bool). These immutable associations add no storage or bodies. Accessors must already belong to the same type, be ordinary methods and agree on static/instance shape. The getter has no declared parameters and returns the property type; the setter takes one value of that type and returns Void. At least one accessor is required. Accessor visibility is preserved independently, including private setters. Ordinary accessor names are allowed; CLI emission adds SpecialName to associated methods.

Non-indexed Int32/Int64/Boolean/String and owned root-class properties are supported. Nominal types must belong to the output assembly; null throws ArgumentNullException, and Void/foreign types throw ArgumentException before mutation. Accessor signatures must use the exact same owned class identity. A unique nonblank name has at most 1024 characters, no control characters or invalid Unicode. Invalid contracts, duplicate names, accessors already associated with another property and more than 256 properties per type throw ArgumentException before mutation. Writing rejects more than 4096 assembly properties with InvalidDataException. The accessor reuse/name limits are bounded producer restrictions, not permanent native rules.

CLI output contains Property, PropertyMap and MethodSemantics rows with ordinary static/HasThis signatures. Native metadata uses existing property/accessor references and exact origin Property tokens. The reader checks signature, owner, instance shape, accessor existence, uniqueness and origins before constructing a throwing reference projection. Outputs without properties retain their previous encoding. New property outputs require the matching bounded reader. Properties do not imply backing fields; Indexed and generic-owner properties are supported by the later slices below; external nominal properties, attributes and default values remain unsupported.

Development API migration (2026-10-01): rebuild consumers of AddProperty and PropertyBuilder.PropertyType and inspect SignatureType.Primitive/ClassType. Existing primitive construction calls use implicit conversion. Nominal properties retain standard CLI CLASS/TypeDef signatures and existing native Named records, including setter parameter references. Static, read-only, write-only and private accessor associations are supported without inventing storage or changing the native binary schema.

Owned property snapshots

IReadOnlyList<PropertyDefinition> ModuleDefinition.Properties { get; }
PropertyDefinition? ModuleDefinition.GetPropertyDefinition(uint metadataToken);
IReadOnlyList<PropertyDefinition> TypeDefinition.Properties { get; }

The module lists physical Property rows in metadata order; types list their declared properties. Lookup returns null for absent/wrong-kind tokens. PropertyDefinition exposes Module, MetadataToken, DeclaringType, Name, ushort Attributes (PropertyAttributes), nullable GetMethod/SetMethod and IReadOnlyList<MethodDefinition> OtherMethods. Accessors are the same owned objects returned by Module.GetMethodDefinition, with no assembly loading or resolution. OtherMethods preserves ordinary Other associations.

GetSignature() returns new owned bytes, including unsupported signature encodings. TryGetPrimitiveSignature(out PrimitiveType type, out bool isStatic) recognizes exact non-indexed Int32/Int64/Boolean/String signatures; failure returns Void/false. This helper decodes the property signature, not accessor compatibility. The general CLI snapshot retains broader signatures opaquely; full CLI verification is not claimed. Default values/custom attributes are not exposed by this snapshot.

Reading enforces at most 4096 Property rows, 16384 MethodSemantics rows and the shared 4 MiB aggregate signature budget. Missing/ambiguous owners, absent signatures and accessors outside the declaring type fail with InvalidDataException. Input buffers and returned signature arrays can be changed without affecting the snapshot.

Root-class locals

Development host API (2026-10-01):

LocalDefinition MethodBuilder.DeclareLocal(TypeBuilder type);
PrimitiveType? LocalDefinition.Type { get; }
TypeBuilder? LocalDefinition.ClassType { get; }

A local is either primitive (Type has a value, ClassType is null) or nominal (Type is null, ClassType is the exact declared root class). Development API migration: LocalDefinition.Type is now nullable; callers that assumed every local was primitive must branch on Type/ClassType. Existing primitive overloads and slot ordering remain. No Void sentinel or System.Type handle represents a nominal slot.

The class overload accepts only nonstatic root classes in the same output graph. Null throws ArgumentNullException; static/foreign classes throw ArgumentException before mutation. All locals share the existing 256-slot limit (InvalidDataException). ClearBody preserves local declarations. Ldloc/Stloc and existing helpers preserve reference identity and require exact declared class identity. Writing rejects wrong primitive/class stores, different nominal classes and loads before a store on every reachable path. Inheritance conversions, null constants and external nominal locals are not admitted.

CLI local signatures use CLASS plus the TypeDef coded index; native locals use the existing Named type contract. The bounded native reader validates local class ownership and shape, then omits implementation locals from reference projections as before. A matching reader is required for these new bodies. API C# tests and direct binary neoCLR execution validate local aliasing/mutation to 42. The subsequent Raven consumer validates source-level aliasing too; see the integration record.

Nominal signatures

Development 2026-10-01. NeoCLR.Metadata.Experimental.Model exposes:

public sealed record SignatureType {
    public PrimitiveType? Primitive { get; }
    public TypeBuilder? ClassType { get; }
    public static implicit operator SignatureType(PrimitiveType type);
    public static implicit operator SignatureType(TypeBuilder type);
    public override string ToString();
}
public class MethodSignature {
    public MethodSignature(SignatureType returnType, IEnumerable<SignatureType> parameterTypes);
    public MethodSignature(PrimitiveType returnType, IEnumerable<PrimitiveType> parameterTypes);
    public SignatureType ReturnType { get; }
    public IReadOnlyList<SignatureType> ParameterTypes { get; }
}
MethodSignature MethodBuilder.Signature { get; }
MethodSignature ImportedMethodReference.Signature { get; }
MethodBuilder TypeBuilder.AddConstructor(MethodSignature signature,
    MethodVisibility visibility = MethodVisibility.Public);

SignatureType has exactly one representation: a defined primitive (including Void only for results), an exact nonstatic TypeBuilder identity, or a bounded vector (see vector declarations). Invalid primitive values and static classes throw ArgumentException; a null class throws ArgumentNullException. Its diagnostic ToString is not a persistent identity. Record equality retains exact builder identity. MethodSignature copies at most 256 parameters; null input throws ArgumentNullException and null/Void parameters or too many parameters throw ArgumentException. Returned lists cannot be modified. Constructors require Void results.

AddFunction (both global and namespaced overloads), AddMethod and AddInstanceMethod now take MethodSignature instead of PrimitiveMethodSignature. Before mutating declarations they reject class types from another builder, including another builder with the same assembly identity. Existing visibility, duplicate-parameter-signature and count limits remain. Method return type does not distinguish overloads. PrimitiveMethodSignature now derives from MethodSignature and retains its primitive-typed ReturnType/ParameterTypes properties; primitive consumers can continue constructing it. Development API migration: rebuild consumers against the changed method signatures. Code inspecting MethodBuilder or ImportedMethodReference signatures must use .Primitive or .ClassType, rather than assuming a primitive enum. Imported read-only method contracts accept primitives and primitive vectors; nominal imports remain unsupported.

CLI output uses CLASS TypeDef signatures; native output uses existing Named type records. Calls, argument stores and returns enforce exact class identity, just like nominal locals. No implicit base conversion, null literal or structural signature support is added. Cross-assembly builder calls with nominal signatures reject at write rather than fabricating a TypeRef. Entries remain parameterless Int32/Void. NativeAssemblyDefinition accepts owned nonstatic Named signature references and remaps them into each reference projection. MethodDefinition preserves CLI blobs, while its primitive recognizers correctly decline nominal signatures. Reference-only output still contains throwing placeholder bodies and must not be executed as the native implementation.

Compiled consumer pattern (covered by NominalSignatureChecks):

var identity = graph.AddFunction("Identity", new MethodSignature(order, [order]));
identity.LoadArgument(0);
identity.Return();
var self = order.AddInstanceMethod("Self", new MethodSignature(order, []));
self.LoadArgument(0);
self.Return();

Here order is graph.AddClass's owned result. The C# contract test passes an allocated instance through both calls, mutates it through a nominal parameter and reads 42 through its alias on .NET and binary neoCLR. Wrong-class arguments/results and foreign signatures reject. Raven additionally validates owned nominal constructor parameters and overloads.

Vector declarations

SignatureType SignatureType.ArrayOf(SignatureType elementType);
SignatureType? SignatureType.ArrayElement { get; }
LocalDefinition MethodBuilder.DeclareLocal(SignatureType type);
SignatureType LocalDefinition.SignatureType { get; }

ArrayOf creates a one-dimensional zero-based vector of Int32, Int64, Boolean, String, an owned non-static root class or another vector (jagged arrays). Null throws ArgumentNullException; Void, by-reference elements and nesting beyond the existing 16-level signature bound throw ArgumentException. Declaration APIs reject foreign element owners before mutation. Method, field and property signatures share this contract; DeclareLocal also rejects Void and enforces the existing 256-slot limit. SignatureType.ArrayElement is null for scalar types. LocalDefinition.Type and ClassType are both null for vectors; use SignatureType to inspect all slot kinds. For example, method.DeclareLocal(SignatureType.ArrayOf(PrimitiveType.Int32)) creates an integer-array slot. Stack joins, calls and stores require exact element identity; covariance is not admitted by this bounded writer.

CLI output uses standard SZARRAY signatures; native output uses ArrayRef, preserving reference identity. The native reader validates elements and reconstructs the same CLI signatures for reference assemblies. These host-only C# APIs remain covered by this manual reference, not the RavenDoc runtime snapshot. Allocation/indexing APIs are described below. C# contract tests execute array parameter/result/local and property/field aliasing on .NET and compare native projections.

Vector body operations

void MethodBuilder.Emit(OpCode opCode, SignatureType elementType);
void MethodBuilder.NewArray(SignatureType elementType);
void MethodBuilder.LoadArrayElement(SignatureType elementType);
void MethodBuilder.StoreArrayElement(SignatureType elementType);
void MethodBuilder.LoadArrayLength();

The typed Emit overload accepts Newarr, Ldelem, Ldelema and Stelem with scalar element types accepted by ArrayOf. Wrong opcode/element/ownership throws ArgumentException; null throws ArgumentNullException, with no body mutation. Helpers have the same validation. Allocation consumes Int32 length and pushes a reference array with default-initialized elements. Loads consume array/index and push an element; stores consume array/index/value. Exact element identity is checked at write time (InvalidDataException); bounds and negative lengths fault at execution. New arrays of reference elements contain null references until initialized. The current API does not expose null literals.

Operand-free Emit(OpCode.Ldlen) consumes an array and pushes native unsigned length, which the bounded flow checker admits into Conv_I4, duplication or discard. Returning it as Int32 without conversion rejects. LoadArrayLength appends ldlen/conv.i4, checks the instruction limit before appending either, and produces Int32. CLI uses standard newarr/ldelem/stelem type tokens and ldlen; native uses the corresponding typed operations. One scalar primitive TypeRef is cached per output kind. No nested arrays, spans, covariance, element addresses or imported nominal elements are admitted. C# tests verify CLI execution and API-produced binary verification/execution on neoCLR.

Indexed property associations

TypeBuilder.AddProperty now also accepts indexed getter/setter methods. Its existing signature is unchanged. PropertyBuilder.ParameterTypes : IReadOnlyList<SignatureType> exposes a copied immutable list of index types, excluding receiver and setter value. For a getter, all parameters are indices; for a setter-only property, all but its last parameter are indices. The final setter parameter must equal PropertyType and its result must be Void. Both accessors must agree on index types and instance/static shape. Primitive, owned-class and vector index types follow MethodSignature rules. A getter may have 256 indices; a setter leaves at most 255 within the method limit.

Properties overload by name plus exact index parameter sequence; return type alone does not distinguish overloads. Duplicate signatures, reused accessors and inconsistent getter/setter signatures throw ArgumentException without adding a property. This relaxes the former name-only uniqueness check. Rebuild development host consumers to use ParameterTypes. Ordinary non-indexed properties have an empty list.

CLI output encodes standard Property signatures/MethodSemantics; native output uses the existing property parameters list and accessor function references. The native reader validates these lists and reproduces CLI reference signatures. PropertyDefinition retains the full signature through GetSignature; its non-indexed TryGetPrimitiveSignature helper deliberately returns false for indexers. No DefaultMemberAttribute is synthesized: Raven source binding already identifies its indexers, while other CLI compilers may need that attribute to recognize source-level indexing. Native introspection's no-index GetValue/SetValue convenience calls are not expanded by this producer change.

Example: define GetItem(Int32) -> Int32 and SetItem(Int32, Int32) -> Void, then owner.AddProperty("Item", PrimitiveType.Int32, get, set). The resulting ParameterTypes contains one Int32. The same name may have a separate Int64-index getter. C# tests execute these accessor associations on .NET and inspect native reference projections.

The C# --indexer-integration <runtime> <fresh-output> check also writes a binary assembly with overloaded getters and a two-index setter-only association. neoCLR loads and verifies its property contracts and executes the accessor calls to 42. This uses existing runtime metadata validation and call instructions, not an indexer opcode or a new runtime introspection invocation API.

Generic method declarations

SignatureType SignatureType.MethodParameter(int index);
int? SignatureType.MethodParameterIndex { get; }
MethodSignature(SignatureType returnType, IEnumerable<SignatureType> parameterTypes,
    IEnumerable<string>? genericParameterNames = null);
IReadOnlyList<string> MethodSignature.GenericParameterNames { get; }

MethodParameter creates a positional method type reference (MVAR); indices outside 0–31 throw ArgumentOutOfRangeException. Declaration/local/instruction use checks the index against the current method's declared arity and throws ArgumentException for invalid scope. Fields and property accessors cannot use method generic parameters. The signature constructor copies up to 32 unique nonblank valid-Unicode names of at most 256 characters without controls; invalid names/counts throw ArgumentException. Names are immutable and preserved in CLI GenericParam rows and native generic_parameters. Unconstrained ownerless functions and static/ordinary instance methods on owned root classes are admitted. Generic constructors, generic types and constraints remain outside this API slice.

For example, new MethodSignature(SignatureType.MethodParameter(0), [SignatureType.MethodParameter(0)], ["T"]) defines Identity<T>(T) -> T. Method generic parameters also work in locals and vector elements. CLI uses MVAR and TypeSpec operands for typed array instructions; native uses MethodTypeParameter. Direct Call/Emit(Call, MethodBuilder) on an open generic definition throws ArgumentException. Generic entries are invalid. Overload uniqueness includes generic arity; return type still does not distinguish methods. MethodDefinition.GenericArity and raw signatures retain generic declarations in native CLI reference projections; primitive-only recognizers continue to decline them. This extends the development MethodSignature constructor; rebuild host consumers.

Instantiated generic calls

MethodBuilder.MakeGenericInstance(params SignatureType[] typeArguments) returns an immutable GenericMethodInstance exposing Definition, copied TypeArguments and substituted Signature. Call(GenericMethodInstance) and Emit(OpCode.Call, GenericMethodInstance) append an owned call. Null arguments throw ArgumentNullException; wrong arity, Void, foreign class/definition, wrong opcode, out-of-scope caller parameters and nested-array substitution throw ArgumentException. Body stack compatibility is validated on write. Only unconstrained static or ordinary instance definitions in the current output are supported. Bounded static imported methods use the separate imported generic contract. For example, body.Call(identity.MakeGenericInstance(PrimitiveType.Int32)) consumes one Int32 for Identity<T>(T)->T and produces Int32. Forwarding may instead pass SignatureType.MethodParameter(0) from a caller that declares that parameter. CLI output uses cached MethodSpec records; native calls carry explicit generic arguments and substituted parameter types. The binary integration test verifies forwarding, Int32/Int64/Boolean instantiations, owned-object identity and generic vector creation/access.

Generic-call regression checks also confirm that caller mutation of the argument array cannot alter an existing instance, and both writers reject a mismatched substituted stack argument before producing an image. Raw Emit(Call, instance) supports forwarded parameters with the same scope and stack contract as Call(instance).

Instance generic calls consume the exact owned declaring-class receiver before explicit arguments and return the substituted result. Receiver slot zero remains separate from MVAR parameter indices. AddInstanceMethod(name, signature) accepts named method parameters; MakeGenericInstance, typed Call and raw Emit(Call, instance) work as for static calls. No virtual-dispatch contract is introduced. Both writers validate receiver stack shape; native reference projection preserves instance/generic flags. Constructors and property accessors cannot declare their own method generic parameters.

Typed local initialization

OpCode.Ldloca accepts an owned LocalDefinition or local index; OpCode.Initobj accepts SignatureType. MethodBuilder.LoadLocalAddress(LocalDefinition) and InitializeObject(SignatureType) expose the same operations. The address may designate an uninitialized local; initialization establishes definite assignment only for that exact local. Both writers reject a mismatched type, non-address operand, an address escaping through value storage/calls/returns, and later loads not initialized on every reachable path. Writable managed-reference parameters are supported as described below. Address values at joins must identify the same local.

OpCode.Ldobj and OpCode.Stobj accept an exact non-Void SignatureType through Emit(OpCode, SignatureType). The corresponding helpers are MethodBuilder.LoadObject(SignatureType type) and StoreObject(SignatureType type). Load consumes an owned local address and pushes its value; store consumes an address followed by the value and leaves no result. Store establishes definite assignment for that local; load requires assignment on every incoming path. Primitive, nominal, vector and scoped generic local types follow the existing signature rules. A null operand throws ArgumentNullException; Void, invalid scope or foreign ownership throws ArgumentException before appending. Instruction limits and invalid stack/address/type or assignment contracts throw InvalidDataException (the latter on writing). CLI uses standard ldobj/stobj tokens, including TypeSpec for generic/vector operands; native emits its existing typed ldobj/stobj. This does not admit pointers, field/array addresses or escaping references. Ldobj/Stobj also accept managed-reference parameters. See LocalObjectChecks.cs for an executable generic copy and branch-merged local update.

MethodBuilder.LoadDefault(SignatureType) declares one scratch local, initializes it and loads its value (three instructions). Types may be primitives, owned root classes, vectors or scoped method parameters; Void, foreign owners and invalid method scope throw ArgumentException. Null arguments throw ArgumentNullException. Local/instruction limits throw InvalidDataException before this helper changes the body; ClearBody retains scratch declarations. Invalid stack/definite-assignment contracts fail during writing. CLI uses ldloca/initobj/ldloc with TypeSpec for generic/vector operands; native uses the same logical operations. Numeric defaults are zero, Boolean false, and reference (string/class/vector) defaults are typed null references. This does not add nullable source syntax or general pointer/byref APIs.

Static generic owners

AssemblyBuilder.AddGenericType(string namespace, string name, IEnumerable<string> genericParameterNames, TypeVisibility visibility = Public) creates an owned static class with one through 32 copied, unique parameter names. It appends the CLI arity suffix to Name (for example Helpers`1); the input simple name must not contain a backtick. Invalid/duplicate names or limits throw ArgumentException; null parameter sequences throw ArgumentNullException. TypeBuilder.GenericParameterNames is an immutable ordinal list. AddGenericType creates static owners; AddGenericClass (below) creates instance owners. Both can associate properties using scoped VAR.

SignatureType.TypeParameter(int index) and nullable TypeParameterIndex represent VAR independently from method MVAR. Index bounds are 0–31 (ArgumentOutOfRangeException); method signatures, locals and typed instruction operands validate the declaring-type scope. Assembly functions cannot use VAR. Entries cannot belong to a generic owner.

MethodBuilder.MakeConstructedReference(IEnumerable<SignatureType> declaringTypeArguments, IEnumerable<SignatureType>? methodArguments = null) binds a generic owner and all method parameters together. It returns immutable ConstructedMethodReference with Definition, copied DeclaringTypeArguments, copied MethodArguments and the simultaneously substituted Signature. Null owner argument sequences throw ArgumentNullException. Wrong arity, Void/null/foreign arguments, nongeneric owners or nested array substitution throw ArgumentException. Supplied caller parameters are validated in the caller scope when emitted; substitution does not capture them. Call(ConstructedMethodReference) and Emit(OpCode.Call, ConstructedMethodReference) require an owned target and supported caller scope; null throws ArgumentNullException, invalid opcode/ownership/scope throws ArgumentException, and instruction/stack failures use InvalidDataException. Open-owner Call and MakeGenericInstance are rejected: bind owner and method arguments together even when the method itself is nongeneric.

CLI uses GenericParam/VAR and a MemberRef on a constructed TypeSpec, optionally wrapped in MethodSpec. Native definitions use open Constructed owners and explicit TypeParameter ordinals; calls substitute owner and method arguments independently. The native reader retains arities/names and validates open ownership before creating a reference projection. These are owned-output references; external method imports use the separate bounded imported generic contract.

Generic reference classes

AssemblyBuilder.AddGenericClass(string namespace, string name, IEnumerable<string> genericParameterNames, TypeVisibility visibility = Public) uses AddGenericType's naming, ownership, arity and error rules, but creates a nonabstract, nonsealed reference class rooted at System.Object in CLI. No constructor is synthesized.

TypeBuilder.MakeGenericInstance(params SignatureType[] typeArguments) returns an immutable GenericTypeInstance with Definition and copied TypeArguments. Equals(GenericTypeInstance?), Equals(object?) and GetHashCode() compare the exact owned definition and arguments structurally; ToString() is diagnostic only. Null arrays throw ArgumentNullException; static/nongeneric owners, arity mismatch, null/Void/foreign arguments or nesting beyond 16 levels throw ArgumentException. Implicit conversion to SignatureType and SignatureType.GenericInstance preserve this identity in parameters, results, fields, locals, arrays and typed initialization. Bare generic TypeBuilder-to-SignatureType conversion is rejected: construct the owner, including with VAR arguments for an open self-reference. Scope is checked on use.

AddField now accepts declaring-type VAR and constructed owned classes (including nested constructions). MVAR in fields is rejected. Generic definition field handles can be emitted only inside their declaring type; constructed external field references are deferred. This keeps CLI/native field access equivalent without losing the owner instantiation. Readonly fields retain declaring-constructor store checks.

MakeConstructedReference now accepts instance methods and constructors as well as static methods. NewObject(ConstructedMethodReference) and Emit(OpCode.Newobj, ConstructedMethodReference) consume substituted constructor parameters and produce the exact constructed class. Call is required for other methods, Newobj for constructors; wrong opcodes, ownership or caller scope throw ArgumentException, null throws ArgumentNullException, and instruction/stack failures throw InvalidDataException. Instance calls require an exactly matching constructed receiver. Constructor chaining remains unsupported. Generic method parameters remain independent of the declaring type, including nested signature substitution.

CLI emits standard GENERICINST, VAR and MemberRef/MethodSpec; native output uses the existing Constructed type and field contracts. The native declaration reader validates field scope and preserves generic fields/constructed signatures in its non-executable CLI reference projection. Constraints, inheritance, external owners and external constructed field handles remain outside this bounded API.

Properties on generic owners

TypeBuilder.AddProperty now accepts declaring-type parameters in the value and index signatures, including vectors and constructed class signatures containing VAR. Both static and instance owners retain their ordinary accessor shape. Accessors cannot declare method generic parameters; MVAR, out-of-range VAR, mismatched owner/result/index signatures and reused accessors throw ArgumentException before adding the association. No storage or bodies are synthesized by AddProperty; index signatures still come from the associated methods and visibility stays on each accessor.

CLI keeps Property/PropertyMap/MethodSemantics and VAR signatures. Native metadata uses canonical open Constructed owners on accessor references. The reader validates exact owner identity, arity and ordered VAR arguments, resolves each accessor under the property's declaring-type scope, and preserves both property signatures and associations in its reference projection. Malformed owner references or scope violations throw InvalidDataException. Use the matching reader for these new producer outputs; the runtime already supports the native representation, so no runtime schema migration is required. This adds no external property import or generic constraints.

Constructed fields

FieldBuilder.MakeConstructedReference(params SignatureType[] typeArguments) returns an immutable ConstructedFieldReference with Definition, DeclaringType (a GenericTypeInstance) and substituted FieldType. Arguments are copied; original field signatures stay open. Constructor arguments follow MakeGenericInstance's bounds, ownership and 16-level nesting rules. Null throws ArgumentNullException; wrong arity, invalid/foreign types or unsupported substitution throws ArgumentException.

MethodBuilder.LoadField(ConstructedFieldReference), StoreField(...) and Emit(OpCode, ConstructedFieldReference) accept Ldfld/Stfld. Caller VAR/MVAR scope and ownership are checked before appending; invalid opcode/scope throws ArgumentException, null throws ArgumentNullException, and instruction limits throw InvalidDataException. Writing checks the exact constructed receiver, substituted value type and existing readonly constructor rule. CLI emits a Field MemberRef on a constructed TypeSpec with the open field signature. Native field indices retain the runtime's constructed receiver identity and layout. External assembly imports remain unsupported; this API accesses owned fields from outside their declaring type and supersedes that earlier restriction.

Nominal type constraints

TypeBuilder.AddBaseTypeConstraint(int parameterIndex, TypeBuilder baseType) adds one owned nongeneric nonstatic root-class bound to a declared type parameter. Null bounds throw ArgumentNullException; invalid indices, repeated parameters, foreign/static/generic bounds throw ArgumentException. GenericConstraints exposes read-only GenericTypeConstraint snapshots with ParameterIndex and BaseType; the public record constructor creates a value only and does not add a constraint to a definition.

CLI uses GenericParamConstraint; native uses TypeBound. Within this root-class producer subset, concrete arguments must be the bound class itself (inheritance/interfaces are not representable yet). Symbolic VAR/MVAR arguments are deferred to runtime substitution. Constructing an invalid concrete reference throws ArgumentException; writing revalidates previous uses after added bounds and throws InvalidDataException. The native reader validates bound ordinals/identity and preserves bounds in the CLI reference projection. Malformed bound metadata throws InvalidDataException. Existing unconstrained outputs retain their encoding; constrained outputs need the matching reader.

This is a nominal bound, not a class/struct/new()/notnull flag. Those categories, method constraints, interface/dependent bounds and dispatch through an open constrained parameter remain separate contracts. The runtime already enforces nominal TypeBound; no schema change is needed for this slice.

Special type-parameter requirements

NeoCLR.Metadata.Experimental.Model.TypeParameterConstraints is a flags enum: None = 0, ReferenceType = 4, ValueType = 8, DefaultConstructor = 16. ReferenceType requires a managed reference (including String and vectors); ValueType requires a supported nonnullable value. DefaultConstructor accepts a value type or a concrete class with a public parameterless instance constructor. The producer currently admits Int32, Int64 and Boolean value arguments.

public IReadOnlyDictionary<int, TypeParameterConstraints> TypeBuilder.SpecialConstraints { get; }
public void TypeBuilder.SetSpecialConstraints(int parameterIndex, TypeParameterConstraints constraints);

The read-only view maps zero-based declared parameter ordinals to requirements. SetSpecialConstraints replaces that ordinal's special flags; None clears them without removing a nominal bound. Invalid ordinals, unknown bits, reference/value combinations and value/nominal-class-bound combinations throw ArgumentException. A reference or constructor flag may coexist with a nominal bound. Set both ValueType and DefaultConstructor for Raven's struct declaration. No method flags are exposed.

var owner = assembly.AddGenericClass("Example", "Box", ["T"]);
owner.SetSpecialConstraints(0, TypeParameterConstraints.ReferenceType |
    TypeParameterConstraints.DefaultConstructor);

Concrete arguments are checked when constructed, except class constructor existence is deferred until writing so definition order does not matter. Final graph validation rejects an unsatisfied requirement with InvalidDataException, including requirements added after an earlier use. Symbolic arguments defer concrete checks to runtime substitution. Flags do not enable construction or constrained dispatch on symbolic T.

CLI uses ordinary GenericParam attributes; native metadata has distinct ReferenceType, ValueType and DefaultConstructor constraint kinds. The declaration reader rejects unknown, duplicate or conflicting flags and preserves accepted flags in reference projections. Native execution needs the matching feature-branch runtime; old runtimes cannot decode these new kinds. Native notvoid/notreference keep their prior meaning. See the integration assessment.

Interface declarations

NeoCLR.Metadata.Experimental.Model exposes:

public TypeBuilder AssemblyBuilder.AddInterface(string @namespace, string name,
    TypeVisibility visibility = TypeVisibility.Public);
public TypeBuilder AssemblyBuilder.AddGenericInterface(string @namespace, string name,
    IEnumerable<string> genericParameterNames, TypeVisibility visibility = TypeVisibility.Public);
public bool TypeBuilder.IsInterface { get; }
public IReadOnlyList<TypeBuilder> TypeBuilder.BaseInterfaces { get; }
public void TypeBuilder.AddBaseInterface(TypeBuilder baseInterface);
public MethodBuilder TypeBuilder.AddInterfaceMethod(string name, MethodSignature signature);
public bool MethodBuilder.IsAbstract { get; }

The factories return owned interfaces with public/internal visibility. Generic names are copied (1–32 distinct names); CLI arity is appended to the supplied simple name. Ordinary type identity/4,095-type limits apply. Invalid identities, visibility, names or duplicates throw ArgumentException; null generic names throw ArgumentNullException. Interfaces are invariant in this API. AddBaseInterface admits directly inherited, owned nongeneric interfaces; generic base instantiations are not exposed yet.

AddInterfaceMethod creates a public abstract instance contract, with supported primitive/owned-class/array/declaring-type-parameter signatures. A null signature throws ArgumentNullException; duplicate/invalid signatures, reserved constructor names, method-level generics or per-owner 256-method limits throw ArgumentException. Calling it on a class, or ordinary AddMethod/AddInstanceMethod/AddConstructor on an interface, throws InvalidOperationException. Interfaces cannot own storage fields; AddField throws InvalidOperationException. AddProperty now associates abstract getter/setter declarations, including declaring-type parameter values and index signatures, using the same validation as class properties. Owned interface references and constructed interface values are admitted as storage, parameter and result signatures, including vector elements and typed defaults. The existing SignatureType.ClassType property denotes a CLI CLASS identity and can refer to a class or interface. MakeGenericInstance now accepts invariant generic interfaces with the existing arity, scope, ownership and argument validation. Interfaces remain invalid nominal class bounds and allocation targets. A signature alone does not declare an implementation; the bounded dispatch API is described below.

var comparer = assembly.AddGenericInterface("Example", "Comparer", ["T"]);
var t = SignatureType.TypeParameter(0);
var compare = comparer.AddInterfaceMethod("Compare",
    new MethodSignature(PrimitiveType.Int32, [t, t]));
// compare.IsAbstract is true; no instructions or locals belong to this declaration.

Writing rejects abstract methods with instructions/locals and direct calls to them with InvalidDataException. Direct interface dispatch and implicit nongeneric implementations are now supported as described below; default/static interface methods remain subsequent work. An abstract method has no CLI body (RVA zero), including in a reference projection: no throwing placeholder is used. CLI uses Interface/Abstract type flags with no base class, and public abstract virtual new-slot method flags. These are ordinary CLI contracts, not extensions; see ECMA-335, Partition II, interface and method-definition rules.

The existing native Interface representation carries contract identity. Its separate type is_abstract field applies to records and remains false; methods carry explicit abstract/virtual flags and empty bodies. No runtime format or instruction change is needed. The native reader validates this shape and preserves interfaces through CLI reference projection. Unknown/mismatched flags, bodies/locals, storage and invalid owner contracts reject with InvalidDataException. Matching reader/producers are required; older experimental readers reject the additional declaration category.

Interface inheritance and properties use standard InterfaceImpl, Property and MethodSemantics metadata. Abstract accessor methods also carry SpecialName and no body. AddBaseInterface returns no value; it adds an edge visible through the read-only BaseInterfaces view. Null throws ArgumentNullException; a noninterface owner throws InvalidOperationException. Foreign, noninterface or generic bases, duplicate edges, cycles and more than 256 direct bases throw ArgumentException. Interface declaration order does not matter. No class-implements-interface contract is implied by this API.

var disposable = assembly.AddInterface("Example", "Disposable");
disposable.AddInterfaceMethod("Dispose", new MethodSignature(PrimitiveType.Void, []));
var iterator = assembly.AddGenericInterface("Example", "Iterator", ["T"]);
iterator.AddBaseInterface(disposable);
var current = iterator.AddInterfaceMethod("get_Current",
    new MethodSignature(SignatureType.TypeParameter(0), []));
iterator.AddProperty("Current", SignatureType.TypeParameter(0), current);

Native reading validates inherited identities, cycles and accessor associations and preserves them in reference projection. Property-only declarations with zero fields may include the writer's empty field-origin arrays; all three arrays must be present and empty when that form is used. Partial/inconsistent field-origin metadata rejects.

Interface implementation and dispatch

IReadOnlyList<TypeBuilder> TypeBuilder.ImplementedInterfaces { get; }
void TypeBuilder.AddInterfaceImplementation(TypeBuilder contract);
void MethodBuilder.CallVirtual(MethodBuilder target);
void MethodBuilder.Emit(OpCode.Callvirt, MethodBuilder target);

AddInterfaceImplementation declares an owned nongeneric interface on a nongeneric root class. Its inherited nongeneric contracts are included. The list is read-only; null throws ArgumentNullException. Static/interface/generic owners throw InvalidOperationException; foreign/generic/noninterface contracts, duplicates or more than 256 direct contracts throw ArgumentException. Writing requires every inherited contract to have a public instance method with the same name, parameter and result signature; missing or incompatible members throw InvalidDataException. Member order does not matter. Explicit MethodImpl mappings are not yet exposed. CLI implementations are virtual/final/new-slot; native implicit matching uses the existing runtime rules.

CallVirtual and raw Emit(Callvirt, target) consume a receiver followed by declared arguments, dispatch to its implementation and push any result. Targets must be owned nongeneric abstract interface methods. Null targets throw ArgumentNullException; foreign/generic/noninterface targets throw ArgumentException without appending an instruction. The existing instruction limit throws InvalidDataException. Stack checking accepts exact references and declared interface upcasts, including inherited contracts; unrelated receivers reject when writing. Arrays remain invariant. Null references can be stored but fault when dispatched; no exception-handling instructions are introduced. Direct Call to an abstract contract still rejects. CLI uses callvirt 0x6f; native output uses the existing callvirt opcode. Reference projections preserve implementations but retain placeholder bodies and must not be executed as native code.

var contract = assembly.AddInterface("Example", "Value");
var get = contract.AddInterfaceMethod("Get", new MethodSignature(PrimitiveType.Int32, []));
var concrete = assembly.AddClass("Example", "Answer");
concrete.AddInterfaceImplementation(contract);
var implementation = concrete.AddInstanceMethod("Get", new MethodSignature(PrimitiveType.Int32, []));
implementation.LoadConstant(42);
implementation.Return();
// In a body with a Value-typed receiver on the stack:
body.CallVirtual(get);

C# contract/integration tests exercise two implementations, inherited contracts, reference arguments and null faults on .NET and the binary neoCLR loader. Generic interface instances are legal signatures but not yet legal targets of this dispatch API. Default/static interface members and class virtual overrides remain separate work.

Imported primitive vectors

bool MethodDefinition.TryGetStaticValueSignature(out MethodSignature? decoded);

Recognizes static nongeneric methods with Int32, Int64, Boolean or String scalar or one-dimensional zero-based vector parameters/results, plus Void only as a scalar result. Success returns an immutable copied MethodSignature; malformed or unsupported encodings return false with null. Parameter counts are canonical CLI compressed integers, bounded to 256. Exact consumption rejects trailing/truncated bytes, Void elements, jagged/multidimensional arrays, byrefs, nominal/generic types and other conventions. This reads declarations only; it neither resolves types nor validates bodies.

AssemblyBuilder.ImportReference and MemberReference.ResolveMethod use this contract and distinguish full vector element signatures when resolving overloads. The existing explicit dependency/core identity, ownership and resolver restrictions remain. For example, a read-only Identity(int[]) -> int[] definition can be imported, called with MethodBuilder.Call, and emitted as ordinary CLI AssemblyRef/TypeRef/MemberRef metadata or as a native assembly. Primitive-only recognition APIs remain narrower.

Vectors retain .NET CLI SZARRAY signatures; no extension or semantic divergence is introduced. Imported nominal and generic signatures still need a separate identity contract. The C# vector checks execute ordinary CLR library/application images and check exact overload resolution, native declaration projection and malformed encodings. The Raven runtime probe executes independently emitted native library/application images with the neoCLR profile.

Imported generic methods

bool MethodDefinition.TryGetStaticGenericValueSignature(out MethodSignature? decoded);
ImportedGenericMethodReference ImportedMethodReference.MakeGenericInstance(params SignatureType[] typeArguments);

public sealed class ImportedGenericMethodReference {
    public ImportedMethodReference Definition { get; }
    public IReadOnlyList<SignatureType> TypeArguments { get; }
    public MethodSignature Signature { get; }
}
void MethodBuilder.Call(ImportedGenericMethodReference method);
void MethodBuilder.Emit(OpCode opCode, ImportedGenericMethodReference operand);

The recognizer returns an immutable signature for static unconstrained methods with 1–32 method parameters, primitives, method parameters (MVAR) and single vectors of those types. Generic parameter names in this callable view are positional T0, T1, etc.; the original image remains unchanged. The generic arity must agree with the GenericParam table, whose indices must be consecutive and whose flags/constraints must be empty. Nongeneric, constrained, out-of-scope, noncanonical or malformed signatures return false/null. Declaring-type parameters and nominal types are outside this subset. Existing nongeneric recognizers keep their narrower behavior.

ImportReference retains this declaration contract; MemberReference.ResolveMethod also matches its generic arity and exact parameter/result types. Instantiation copies one non-Void consumer-scoped signature type per method parameter, including owned or imported reference types, constructions, supported vectors and caller generic parameters. Null arrays throw ArgumentNullException; wrong arity, foreign type ownership, a nongeneric definition or substitutions producing a nested vector throw ArgumentException. Definition exposes the immutable imported reference, never a mutable dependency builder. TypeArguments is the copied ordered sequence; Signature substitutes method parameters and may retain caller-scoped parameters until emission.

Call and raw Emit(Call, reference) append the same generic call. Null references throw ArgumentNullException; wrong opcodes, consuming owners or caller generic scopes throw ArgumentException. Method/declaring-type parameter indices are checked against the caller at emission. An uninstantiated generic ImportedMethodReference cannot be called. Instruction limits and stack/type mismatches continue to throw InvalidDataException on append/write. CLI output uses a standard MethodSpec targeting an external MemberRef. Native output uses the existing generic_arguments call contract; there is no format or opcode change.

For example, import First<T>(T[]) -> T, instantiate with PrimitiveType.Int32, then pass an Int32 vector to Call. The C# tests execute the resulting separate library and application on the CLR. Raven's native-profile generic library probe verifies and runs the equivalent binary boundary in neoCLR, including consumer-owned nominal arguments, alias mutation, external constructions and caller method/owner parameter forwarding. Imported generic declaring types, cross-dependency nominal types in the imported definition signature and constraints remain unsupported; this is not general collection import support.

Lifecycle direction reaffirmed 2026-10-01

.NET metadata remains the baseline; neoCLR extensions are explicit. This Cecil-like library is intended to support inspection, modification, creation from nothing and writing through familiar definition/reference concepts. Current loaded snapshots are immutable and preserve original bytes; producer graphs are editable. General editing of arbitrary loaded assemblies through one model is not implemented yet. The bounded import APIs described above must not be read as a permanent split or a new metadata format. Assembly-level functions already exist, with a CLI <Module> compatibility representation; new generic imports add no further format extension.

Imported type signatures

ImportedTypeReference AssemblyBuilder.ImportReference(TypeDefinition definition, AssemblyIdentity dependencyCoreLibrary);

public sealed class ImportedTypeReference : IEquatable<ImportedTypeReference> {
    public AssemblyBuilder Owner { get; }
    public AssemblyIdentity AssemblyIdentity { get; }
    public string Namespace { get; }
    public string Name { get; }
    public int GenericArity { get; }
    public IReadOnlyList<SignatureType> TypeArguments { get; }
    public ImportedTypeReference MakeGenericInstance(params SignatureType[] arguments);
    public bool Equals(ImportedTypeReference? other);
    public override bool Equals(object? obj);
    public override int GetHashCode();
    public override string ToString();
}
ImportedTypeReference? SignatureType.ImportedType { get; }
public static implicit operator SignatureType(ImportedTypeReference type);

ImportReference copies the exact assembly identity, namespace, metadata name and arity from a public top-level reference class/interface declaration. It interns definition references per consumer and rejects conflicting dependency MVIDs. The explicit core identity must match the consumer. Value types, nested/static/nonpublic types, signed or flagged dependencies, self imports, constrained/variant generic definitions and arities above 32 are unsupported. Generic indices must be consecutive. Unsupported contracts and limits throw InvalidDataException; null inputs throw ArgumentNullException. The consumer admits at most 4096 imported type names and 256 dependency identities. The overload addition means a null literal in ImportReference needs an explicit MethodDefinition or TypeDefinition cast to select the intended overload.

A nongeneric reference converts directly to SignatureType. A generic definition first needs MakeGenericInstance, which copies one non-Void consumer-scoped argument per parameter. Arguments may include the consumer's own classes, other imported reference types and scoped generic parameters; scope is checked at signature use. Depth is limited to 16. Null arrays throw ArgumentNullException. Wrong arity, already constructed/open signature use, foreign ownership, Void/null arguments and excessive depth throw ArgumentException. Generic substitution recurses into imported constructions.

Owner identifies the consumer; AssemblyIdentity/Namespace/Name identify the external definition. GenericArity belongs to the definition; TypeArguments is empty for definition references and copied/read-only for constructions. Equality compares consumer ownership, exact external identity and ordered arguments; GetHashCode agrees. ToString is diagnostic only. No mutable dependency TypeBuilder is exposed. Imported constructions are accessed through SignatureType.ImportedType, while GenericInstance still describes owned types. LocalDefinition.SignatureType also carries these types; ClassType remains null for them.

Example: import a dependency's Box<T> TypeDefinition, create an Order class in the consumer, and call box.MakeGenericInstance(order). Use the resulting reference in MethodSignature, fields, locals, vectors and default-value initialization. Standard CLI output uses AssemblyRef/TypeRef and CLASS/GENERICINST signatures (TypeSpec for typed IL operands). The native writer uses existing Named/Constructed identities scoped to the dependency manifest. Its reference projection preserves external scope rather than inventing local definitions. Unknown scopes, noncanonical names and arity mismatches reject. No native format, instruction or schema extension was added. Earlier experimental metadata readers may reject these external signatures; rebuild consumers with this API.

Native dependencies must use the metadata writer's existing format-5 naming contract; importing an arbitrary CLI declaration does not translate its executable implementation. Imported references are recorded as native dependencies even when not subsequently used. The reader resolves no dependencies and verifies no external constraints/layouts. Method/constructor imports containing these signatures and mappings to translated System's original native identities are not yet implemented. This slice supplies the signature contract required for that work; Raven's collections sample remains blocked.

Validation: C# tests inspect actual CLR generic scopes and execute the output, then check native declaration projection and malformed dependency rejection. The --imported-type-integration <neoclr> <fresh-output> test mode loads a separate native library/application, verifies and returns 42, including external interface and Box<consumer Order> fields/defaults and generic forwarding.

Imported nominal method signatures

The existing AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) overload decodes dependency-local CLASS and GENERICINST signatures into consumer-owned ImportedTypeReference values, including supported vectors and method parameters. A method can return Box<T>, accept it, or accept a vector of a dependency interface. The method owner still must be nongeneric and top-level, and the method static. The exact dependency definition snapshot supplies type name, arity and reference category; module-local tokens are never compared across assemblies.

The immutable ImportedMethodReference.Signature exposes the remapped contract. Import interning still checks exact identity/MVID/token and signature equality. Scoped generic arguments and substituted signatures use the existing MakeGenericInstance API. Malformed/truncated/noncanonical encodings, missing definitions, excessive nesting, value-type encodings, nested vectors and unsupported TypeRef signatures throw InvalidDataException. Null inputs retain ArgumentNullException behavior.

Standard CLI TypeRef/MemberRef/MethodSpec output and native dependency-scoped named signatures are retained, without runtime format changes. Direct calls through foreign mutable producer methods do not gain nominal support; use the explicit snapshot import. Primitive-only recognizers and MemberReference.ResolveMethod retain their documented narrower subset. General nominal MemberRef resolution is still pending.

The C# contract tests execute a library factory returning an object and a library reader accepting it on the CLR. Raven's native probe additionally tests a generic factory, consumer-owned payload aliases, interface-vector overload matching and missing-method rejection. Nullable annotations are not retained by the current declaration projection; these cross-assembly factory contracts use nonnullable references. Imported value/union contracts, constructors/instance calls and translated-System native identities remain unsupported. Native evidence.

Owned value types

TypeBuilder AssemblyBuilder.AddValueType(string @namespace, string name,
    TypeVisibility visibility = TypeVisibility.Public);
TypeBuilder AssemblyBuilder.AddGenericValueType(string @namespace, string name,
    IEnumerable<string> genericParameterNames,
    TypeVisibility visibility = TypeVisibility.Public);
bool TypeBuilder.IsValueType { get; }
bool TypeDefinition.IsValueType { get; }

AddValueType creates an owned, sealed sequential-layout CLI type deriving from the configured core's System.ValueType. AddGenericValueType adds one through 32 invariant, unconstrained parameters and appends the normal metadata arity suffix to the name. Names/visibility/duplicate and resource checks match AddClass/AddGenericClass; invalid inputs throw ArgumentException and null generic parameter collections throw ArgumentNullException. Neither method creates an instance constructor. The definition supports static methods, supported inline instance fields (see the union payload foundation update), defaults, parameters/results, locals, vectors and generic construction/arguments. Public/internal visibility is preserved in both output formats.

TypeBuilder.IsValueType reports the producer category. TypeDefinition.IsValueType reports whether the input directly extends a type named System.ValueType or System.Enum; this is metadata classification, not runtime loading or validation of the base assembly. SignatureType.ClassType is retained as the compatibility property name for an owned nongeneric nominal identity, including a value type. GenericTypeInstance.Definition likewise distinguishes classes, interfaces and value types using the definition flags. CLI encoding uses VALUETYPE and GENERICINST VALUETYPE for these types. Native output uses the existing non-reference, sealed type shape; native reading and CLI projection preserve it without a new instruction or format revision.

ValueType and DefaultConstructor generic requirements admit these definitions; ReferenceType requirements and nominal class bounds reject them. Instance methods, constructors and interface implementation are not yet supported for producer value types (InvalidOperationException). Direct nominal field storage is rejected with ArgumentException, avoiding unsupported recursive inline layouts. Declaring-type parameters are allowed, with types substituted at construction. StoreField/Emit(Stfld, ...) on a value-type owner require an address obtained from LoadLocalAddress for an initialized local of the exact owner type. Reads accept either that address or a value copy. Uninitialized, mismatched-owner and value-copy stores throw InvalidDataException on write; partial field assignment does not initialize a local. Readonly field restrictions remain unchanged. Static properties may use static accessors as elsewhere.

Imported value-type definitions still reject: importing them as reference types would corrupt signature/category semantics. Native reader checks the bounded shape and rejects unsupported field storage before projection. These are current producer limits, not permanent neoCLR rules; runtime value types already exist beyond this subset.

The C# checks execute defaults, field reads, static/generic forwarding and vector storage on CLR and native neoCLR, both returning 42. They also test CLR reflection, read snapshots, native projection, constraints and invalid shape/storage rejection. Evidence. This is a prerequisite for Raven union emission, not a completed collections gate. Generic payload storage and addressed local field mutation are now tested: value payloads and arrays retain copies, while reference payloads retain their aliases. The legacy native managed-reference store returns an inhabited Void value; the native writer appends a pop (and adjusts branch offsets) to preserve CLI stfld stack behavior. No runtime opcode or format change is introduced.

Definition-first model (author direction, 2026-10-01)

Planned refactor, not implemented API: definitions are the canonical editable metadata model. Builders are optional convenience facades over those exact objects; writers consume definitions. A caller must be able to construct an assembly/module, a TypeDefinition with attributes and an explicit base-type reference, and field/method members, then write it without using a builder. A builder must expose its definition and preserve object identity: editing that definition affects subsequent output without copying or synchronizing a second graph.

The current implementation instead uses immutable loaded definition snapshots and a separate mutable producer graph. This is an architectural gap. The earlier bounded builder APIs are compatibility surfaces, not the long-term source of truth. The Cecil comparison is about the editable graph and ownership model, not dependence on host reflection or an identical API spelling. Value-type classification follows the base-type/category contract; sealed/layout attributes alone do not establish that a type is a value type. Explicit target core identities remain essential for neoCLR.

The next implementation slices are:

  1. Establish constructible assembly/module/type/field definitions and explicit type references with ownership-aware member collections. Use the author's manual struct example as a C# contract test. Encode a sealed sequential value type based on the configured core's ValueType and inspect/load the produced CLI/native assembly.
  2. Move existing producer state into definitions and adapt builders into facades. Keep existing Raven-facing calls compatible where practical. Check that a builder and direct edits see the same definition objects and encode equivalent output; temporary adapters must not become a second authoritative graph.
  3. Move method signatures, locals and instructions into definition/body objects, retain type-safe/raw Emit helpers, and make both writers consume that representation. Preserve symbolic branch targets and recalculate offsets on encoding; an ILProcessor can then provide insertion helpers without requiring a separate body model.
  4. Materialize supported read metadata and bodies into the same definitions for read–edit–write. Preserve opaque unchanged input where possible and explicitly reject edits that would discard unsupported metadata. Do not claim arbitrary loaded assembly editing until preservation and executable roundtrip tests establish it.

Validation must cover manual construction, ownership/identity, edits made through both surfaces, repeated writing and supported loaded roundtrips, plus existing C# tests and Raven-to-native consumers. The roadmap's unchanged collections/runtime-library acceptance remains the overall goal; this author-directed refactor precedes more builder-only feature expansion. No new constructor or mutation API in this plan is shipped yet.

Cecil alignment reference (reviewed 2026-10-01)

The author endorsed alignment with Mono.Cecil where it matters and supplied that repository as the reference. Review of its current source supports the following direction; these are refactor requirements, not claims that our API already implements them:

  • AssemblyDefinition creation, reading and writing address the same object model. Follow that lifecycle and familiar definition/reference terminology. AssemblyDefinition source.
  • Type definitions expose attributes, base types and editable members. Follow that shape; derive value-type classification from the base/category contract rather than a collection of independent flags. Cecil's IsValueType checks System.ValueType/Enum and does not support setting that property directly. TypeDefinition source.
  • Member collections maintain declaring-owner relationships when adding/removing members. Adopt explicit ownership invariants to prevent accidentally sharing a definition between modules/types. Exact reparenting behavior remains a design/validation choice. MemberDefinitionCollection source.
  • Module-scoped importing and type-system access provide reference context. Preserve this separation from runtime loading; neoCLR must retain explicit core/dependency identity rather than infer its target from host reflection. ModuleDefinition source.
  • An ILProcessor operates on a method body's instruction collection and supports typed raw emission plus insertion/removal/replacement. Adopt this relationship; convenient Call/LoadArgument helpers may sit above it. Retargeting branches and maintaining valid bodies need explicit rules and tests, not an assumption that list replacement does all repairs automatically. ILProcessor source.

The benefit is one familiar editable graph for manual callers, compiler emission and inspection. The costs are migration of existing builder-owned state, ownership/cache invalidation rules and preservation testing for loaded content. We are aligning the model, not promising drop-in Cecil API/binary compatibility or adding a Cecil runtime dependency. neoCLR assembly-level functions and future metadata categories remain explicit extensions to that shared model. Different encoders consume it and validate supported target capabilities; they do not determine the public graph's shape.

Authored definitions: first migration slice

Development API, 2026-10-01. CLI metadata and CIL remain the baseline; this slice changes the authoring model without changing the wire format or instruction set. It implements only the assembly/type/field part of the definition-first plan above.

API Contract
AssemblyDefinition.CreateAssembly(AssemblyIdentity identity, AssemblyIdentity coreLibrary) Creates an authored assembly with explicit target identity and core contract. Existing producer identity validation applies.
AssemblyDefinition.Write() Encodes authored definitions; loaded snapshots still return owned original bytes.
AssemblyDefinition.WriteNativeAssembly() Encodes authored definitions through the existing native writer. Loaded snapshots throw InvalidOperationException.
AssemblyBuilder.Definition / AssemblyBuilder.ForDefinition(AssemblyDefinition) Returns the same assembly/facade without copying declarations. Null input throws ArgumentNullException; loaded input throws InvalidOperationException.
ModuleDefinition.ImportReference(AssemblyIdentity scope, string namespace, string name) Creates an explicitly scoped reference; does not load a dependency or consult host reflection. Invalid/null arguments reject. Explicit resolution requires matching assembly identity.
TypeDefinition(string namespace, string name, uint attributes, TypeReference? baseType) Creates a detached declaration. Attachment admits nongeneric root classes, static classes or sealed sequential value types with the same module's explicitly imported core Object/ValueType base. Unsupported shape, foreign ownership or duplicate name throws ArgumentException.
TypeDefinition.BaseType Base definition reference; use BaseTypeSignature to retain native construction arguments. CLI base decoding remains pending.
TypeDefinition.BaseTypeSignature Native/authored base signature with declaration-scoped generic arguments; null when absent. CLI snapshots throw NotSupportedException.
FieldDefinition(string name, ushort attributes, SignatureType fieldType) Creates a detached instance field. Supports Private, Assembly or Public access and optional InitOnly; nonvoid signature required. Value-type storage retains existing primitive/generic-payload restrictions.
FieldDefinition.FieldType Authored signature; null for opaque loaded signatures. GetSignature() rejects authored fields until encoded/read; use FieldType instead.
FieldDefinition.Name Authored fields can be renamed with Unicode/name and duplicate checks. Loaded edits throw InvalidOperationException.
TypeBuilder.Definition / FieldBuilder.Definition Exact declaration object consumed by the facade. Builder field creation appends to the definition collection.

ModuleDefinition.Types and TypeDefinition.Fields return IList<T> instead of IReadOnlyList<T>: a development API source compatibility change. Authored lists support appending only. Insertion elsewhere, replacement, removal and clearing throw NotSupportedException. Ownership is exclusive; attach a type to its module and fields to their type. Detached Module properties are unset until attachment. Physical tokens remain zero until encoding and rereading; token lookup is a loaded-image operation. ModuleDefinition.Fields reflects current authored fields.

Method bodies, property associations and generic parameter declarations still use the existing builder representation. Authored method/function views and EntryPoint expose canonical declarations; use the builder facade to create type methods and edit bodies. Other snapshot metadata views are not materialized authored views. Loaded definitions remain read-only, byte-preserving snapshots. Writers currently use builder encoding adapters; this is not completion of canonical method/body or reader/editor migration.

var assembly = AssemblyDefinition.CreateAssembly(identity, targetCoreIdentity);
var module = assembly.MainModule;
var valueType = module.ImportReference(targetCoreIdentity, "System", "ValueType");
var type = new TypeDefinition("Example", "MyStruct", 0x109, valueType);
type.Fields.Add(new FieldDefinition("MyField", 0x6, PrimitiveType.Int32));
module.Types.Add(type);
byte[] pe = assembly.Write();

Validation: AuthoredDefinitionChecks covers exact facade identity, direct declarations, renaming, ownership rejection, CLR shape/execution and native verify/run (42). --authored-definition-integration <runtime> <fresh-directory> reproduces the native case. The 76 C# contract groups and Raven external-signature/generic-library runtime probes pass. The broader collections Optional<Order> gate remains unchanged.

Shared method declarations

The next migration slice adds MethodBuilder.Definition, with the declaration owning its name, authored namespace, access/static flags and immutable signature. MethodDefinition.AuthoredSignature returns that same MethodSignature (null for loaded declarations); MethodDefinition.Namespace returns the authored namespace (null for loaded physical rows). ModuleDefinition.Methods, .Functions, TypeDefinition.Methods and AssemblyDefinition.EntryPoint return those exact objects. Global functions retain a null declaring type. Type-method and aggregate method collections remain read-only views. The following slice enables direct assembly-function construction; mutable body definitions remain pending.

MethodDefinition.Attributes includes context-derived CLI flags for constructors, property accessors, interface contracts and implementations. Inspection and PE writing share flag calculation; writer-side accessor classification stays precomputed. Authored GetSignature() throws InvalidOperationException; raw signature recognizers remain loaded-image operations. Write and reread for physical tokens/signatures. EntryPointToken remains zero before serialization. Existing typed helpers and raw Emit overloads continue to operate through the method builder.

Validated by 76 C# groups, including declaration identity and accessor/interface flag round trips; direct-struct CLR/native execution returns 42. Raven's external-signature native probe also passes with the rebuilt metadata dependency.

Direct assembly-level function construction

new MethodDefinition(string name, MethodSignature signature, MethodVisibility visibility = MethodVisibility.Public, string @namespace = "") creates a detached static function. Public/Internal access is supported; other access throws ArgumentOutOfRangeException. Null signatures throw ArgumentNullException; invalid/reserved names and namespaces throw ArgumentException. Final Unicode/body validation remains at writing, preserving existing builder behavior.

Append to assembly.MainModule.Functions to attach and validate signature ownership, uniqueness and the 256-function limit. This collection returns IList<MethodDefinition> instead of IReadOnlyList<MethodDefinition> (development API change). Loaded collections reject appends; authored collections reject replacement/removal/reordering. Attached or loaded declarations cannot be attached again. A failed foreign-signature attachment does not transfer ownership. Type-owned methods still require TypeBuilder construction.

MethodBuilder.ForDefinition(MethodDefinition) returns the existing body helper facade. Null throws ArgumentNullException; detached or loaded input throws InvalidOperationException. AssemblyDefinition.EntryPoint can now be set on authored assemblies, including null for a library. Foreign/detached entries throw ArgumentException; loaded assignment throws InvalidOperationException. Writing still validates the entry signature/body. Detached Module is unset until attachment.

var answer = new MethodDefinition("Answer", PrimitiveMethodSignature.Int32(0, true),
    @namespace: "Example");
assembly.MainModule.Functions.Add(answer);
var answerBody = MethodBuilder.ForDefinition(answer);
answerBody.LoadConstant(42);
answerBody.Return();
var main = new MethodDefinition("Main", PrimitiveMethodSignature.Int32(0, true));
assembly.MainModule.Functions.Add(main);
assembly.EntryPoint = main;
var mainBody = MethodBuilder.ForDefinition(main);
mainBody.Call(answerBody);
mainBody.Return();
byte[] image = assembly.Write();

This follows Cecil's declaration/body-helper separation while preserving neoCLR's assembly-level function category. Existing CLI global-function projection and native encoding remain unchanged. The executable test combines this call with direct struct field storage; CLR/native return 42. All 76 C# contract groups pass. Arbitrary instruction editing, canonical body definitions and loaded read/edit/write remain future slices.

Direct static type-method construction

new MethodDefinition(string name, ushort attributes, MethodSignature signature) creates a detached static type method. Attributes accept Static plus Public, Assembly or Private, and optional HideBySig. The subsequent instance/constructor extension is described below. Abstract, virtual and other flags remain unsupported by this constructor; existing builders retain their previous bounded contracts. Null signatures throw ArgumentNullException; unsupported flags, empty/overlong names and .cctor throw ArgumentException.

Attach the declaring type to its authored module, then append the method to TypeDefinition.Methods. This property returns IList<MethodDefinition> instead of IReadOnlyList<MethodDefinition> (development source compatibility change). It is append-only for authored types and read-only for loaded types. Adding to a detached type throws InvalidOperationException. Attachment checks signature ownership and scope, duplicate name/parameter/generic-arity signatures and the 256-method limit. Foreign or already attached declarations reject without moving ownership. Explicit function declarations and type-method declarations cannot be interchanged. Interface methods continue to require the abstract-contract builder API.

MethodBuilder.ForDefinition supplies existing typed helpers and raw Emit overloads. The method's namespace follows its declaring type, and its declaring type/module are the exact authored objects. Existing builder-created instance methods, constructors and interface contracts also enter this same collection. Method bodies remain in the builder representation. CLI attributes and encodings are unchanged.

var answer = new MethodDefinition("Answer", 0x96,
    PrimitiveMethodSignature.Int32(0, true)); // Public | Static | HideBySig
attachedType.Methods.Add(answer);
var body = MethodBuilder.ForDefinition(answer);
body.LoadConstant(42);
body.Return();

Validation extends the manual executable to call a directly declared static type method through an assembly-level helper. CLR and neoCLR return 42. C# contracts cover shared identity, access flags, duplicate/foreign attachment, detached-owner rejection and unsupported method categories. The broader collections Optional<Order> gate is unchanged.

Direct instance methods and constructors

The CLI-attribute MethodDefinition(string, ushort, MethodSignature) constructor now also accepts nonstatic instance methods and .ctor declarations. Public/Assembly/Private and optional HideBySig apply as before. A .ctor must be nonstatic, return Void and declare no method generic parameters. It may specify SpecialName and RTSpecialName together; writing supplies both flags as it does for existing builder constructors. Those flags on ordinary methods, partial constructor flag pairs, .cctor, arbitrary virtual/abstract flags and invalid constructor signatures throw ArgumentException.

Attachment requires a reference-class owner for instance methods/constructors; static and value-type owners throw InvalidOperationException before ownership transfer. Direct interface contracts are covered by the subsequent interface slice below. Signature ownership, generic scopes, access and readonly-field rules reuse the existing method/body contracts. Detached method bodies still require attachment before MethodBuilder.ForDefinition succeeds.

var constructor = new MethodDefinition(".ctor", 0x1806,
    new MethodSignature(PrimitiveType.Void, new[] { PrimitiveType.Int32 }));
attachedClass.Methods.Add(constructor);
var body = MethodBuilder.ForDefinition(constructor);
body.LoadArgument(0); // receiver
body.LoadArgument(1);
body.StoreField(ownedFieldBuilder);
body.Return();

As with the existing producer, root-class CLI constructors initialize System.Object; native construction uses the existing root-object path. Constructor chaining, value-type instance methods and class virtual dispatch are not added by this authoring change. No wire format or CIL changes are introduced. This uses the Cecil-like definition/body helper separation while retaining the current bounded execution contract.

The C# executable fixture constructs a manually declared reference class, initializes its private readonly Int32 field in a manual constructor, calls a manual instance reader, and carries the result through the function/type-method/struct path. CLR and neoCLR return 42. Tests also compare emitted constructor/instance flags and reject invalid constructor signatures and owner categories. Canonical body definitions, direct interface contracts and loaded editing remain pending; the collections Optional<Order> gate is unchanged.

Direct interface declarations and dispatch

A nongeneric TypeDefinition with Interface | Abstract and optional Public attributes can now be attached directly. Its base reference must be null and it cannot declare fields. Unsupported bases/storage reject before module ownership is transferred.

The CLI-attribute MethodDefinition constructor admits public instance contracts with Abstract | Virtual | NewSlot together (optional HideBySig). Partial flag combinations, static/private contracts, constructors and method-generic contracts reject with ArgumentException. Attach these declarations to an authored interface; an abstract contract on a class or concrete declaration on an interface throws InvalidOperationException. These bounds match existing interface builder support.

var contract = new TypeDefinition("Example", "IRead", 0xa1, null);
assembly.MainModule.Types.Add(contract);
var read = new MethodDefinition("Read", 0x5c6,
    PrimitiveMethodSignature.Int32(0, true));
contract.Methods.Add(read);
// Use MethodBuilder.ForDefinition(read) as the target of CallVirtual.

The contract remains bodyless. Writing rejects instructions or locals on it through existing abstract-method validation. Relationships (base interfaces and class implementations) still use TypeBuilder.AddBaseInterface/AddInterfaceImplementation; they have not yet moved to directly mutable definition collections. Generic interface definitions still require builders. No class virtual dispatch, static interface methods, default implementations or new instruction encodings are introduced.

The manual executable declares IRead and Read directly, registers the class implementation through the existing helper and calls it with CallVirtual. CLR and neoCLR return 42. All 76 C# groups pass, including existing multi-implementation/inherited interface tests and new invalid-owner/flags/interface-storage checks. Raven's rebuilt external-signature probe also passes. Canonical bodies, relationship definitions and loaded editing remain pending; this does not resolve the collections Optional<Order> import gap.

Authored interface relationships

InterfaceImplementation(TypeReference interfaceType) creates an unattached relationship; null throws ArgumentNullException. InterfaceType retains the exact immutable reference. DeclaringType is null until successful attachment. Append to the new TypeDefinition.Interfaces : IList<InterfaceImplementation> on an attached authored type. For interfaces this declares inheritance; for root classes it declares implicit implementation. Builders add to this same collection; their existing handle lists are encoding caches over these immutable edges.

The original local overload requires attached, same-assembly nongeneric interfaces. External overloads are documented under external interface declarations. Foreign, noninterface, detached, unresolved, duplicate or cyclic targets and reused edge objects throw ArgumentException; unsupported/detached owners throw InvalidOperationException. Replacement, removal and clearing throw NotSupportedException. Loaded Interfaces access also throws NotSupportedException until reader materialization is implemented. No resolver/host loading occurs during attachment. Existing implementation completeness, 256-edge limits and cycle checks remain in force.

derivedInterface.Interfaces.Add(new InterfaceImplementation(baseInterface.ToReference()));
implementingClass.Interfaces.Add(new InterfaceImplementation(derivedInterface.ToReference()));

The manual inherited-interface dispatch case executes on CLR/neoCLR (42). All 76 C# groups pass, including duplicate/cycle/category rejection. CLI InterfaceImpl and native encoding remain unchanged. Generic relationships and loaded editing remain unsupported.

Definition-owned method bodies

MethodDefinition.Body : MethodBodyDefinition now owns authored instruction, local and symbolic-label storage. Existing MethodBuilder helpers and raw Emit overloads operate on this same storage, as do the CLI/native writer adapters. The definition returns one stable body object. Loaded Body access throws NotSupportedException; loaded-body materialization and editing remain pending. An abstract declaration may have an empty Body, but writing rejects instructions or locals on it.

Member Contract
MethodBodyDefinition.Method Exact owning MethodDefinition.
Locals : IReadOnlyList<LocalDefinition> Cached, live read-only view of declared slots; existing builder-owned handles remain compatible.
Labels : IReadOnlyList<BranchLabel> Cached, live read-only view of allocated label handles.
ClearInstructions() Removes instructions and label marks, preserving locals and label handles. Referenced labels must be marked again. Writers revalidate the result.

Use MethodBuilder.ForDefinition(method) for emission after attachment. ClearBody now delegates to Body.ClearInstructions. Read-only local views no longer allocate a wrapper on each getter call; no broader performance improvement is claimed. This moves canonical storage without introducing a second instruction graph or changing CLI/CIL/native lowering. Public arbitrary instruction lists, insert-before/after, body decoding, exception regions and independent local construction are not added.

C# tests verify method/body/local/label identity, clear-and-rebuild with a retained branch label and locals, CLR execution (42), and rejection of loaded Body access. The native manual object/interface/struct case replaces a body through the definition API before emission and returns 42. All 76 contract groups and the rebuilt Raven external-signature probe pass. Property/generic-definition migration and loaded editing remain open, as does the collections Optional<Order> target gap.

Shared authored property declarations

PropertyDefinition(string name, SignatureType propertyType, MethodDefinition? getter = null, MethodDefinition? setter = null) creates a detached association. It requires a nonnull value type and at least one authored accessor; null type throws ArgumentNullException, missing/loaded accessors throw ArgumentException. Append to the attached owner's TypeDefinition.Properties : IList<PropertyDefinition> after attaching accessors. The collection is append-only; loaded collections remain read-only. Changing its former IReadOnlyList return type is a development API compatibility change.

Attachment reuses name/Unicode, non-Void signature, scope/ownership, accessor reuse, getter/setter shape, index parameters, duplicate and limit validation. Invalid associations throw ArgumentException without attaching; detached owners throw InvalidOperationException. Accessors must be nongeneric ordinary methods on that owner. Their access and staticness remain on method definitions. Authored property flags are zero; custom attributes, defaults and arbitrary PropertyAttributes authoring are not introduced.

PropertyType and ParameterTypes expose authored value/index signatures (null for loaded opaque signatures). GetMethod/SetMethod return the exact authored declarations. Accessing DeclaringType before attachment throws InvalidOperationException. Authored GetSignature throws InvalidOperationException; encode and read for physical blobs. Raw primitive recognition remains a loaded-signature operation. PropertyBuilder.Definition returns this same object; the builder delegates its state. ModuleDefinition.Properties includes authored properties. Loaded raw rows and their preservation behavior remain unchanged.

var property = new PropertyDefinition("Value", PrimitiveType.Int32, getterDefinition);
attachedType.Properties.Add(property);

The manual executable associates its instance reader with Value. CLR reflection constructs the class and reads Value as 42; native execution still returns 42. All 76 contract groups, including existing getter/setter/indexer tests, pass; Raven's rebuilt external-signature probe passes. No property wire encoding or compiler admission change is introduced.

Builder direction clarified by the author (2026-10-01)

Definitions/references and inspection/manipulation remain Cecil-like. Builders are a separate convenience layer over those same definitions and should increasingly follow Reflection.Emit-style generation patterns. They are not a replacement or drop-in implementation of System.Reflection.Emit, and this direction does not require a host Reflection.Emit dependency. Typed helpers and raw emits remain complementary.

This is an architectural direction, not a completed API rename or compatibility claim. Future Define-style construction and body-helper decisions should follow that direction while preserving target-specific capability checks and explicit identities. The property migration here shares declarations; existing Add-style entry points remain supported.

Direct generic types and shared constraint storage

TypeDefinition(string namespace, string name, uint attributes, TypeReference? baseType, IEnumerable<string> genericParameterNames) creates a detached generic root class, value type or interface. Supply a simple name without backtick/arity; the constructor appends the CLI arity suffix. One through 32 unique valid names are copied using the existing signature-name rules. Null input throws ArgumentNullException; invalid names, empty/duplicate/over-limit parameters throw ArgumentException. Attachment applies the existing category/base/ownership restrictions; generic static classes remain unsupported. Pending fields validate VAR references against the declaring arity, including supported generic value-type payload fields.

TypeDefinition.GenericParameterNames is an immutable authored list shared by the builder; it is null for loaded snapshots whose names are not materialized. Existing GenericArity continues to report loaded arity. SpecialConstraints and GenericConstraints expose cached live read-only views of definition-owned storage. Loaded access throws NotSupportedException. Existing TypeBuilder.SetSpecialConstraints/AddBaseTypeConstraint helpers validate and update that storage. Nominal constraints retain their existing GenericTypeConstraint builder bound handles; independent generic-parameter/constraint reference objects and loaded constraint editing are future work.

The manual executable declares Identity<T> directly, adds Pass(T):T directly, constrains T to a value type through the helper, and calls Identity<Int32>.Pass. CLR reflection confirms the parameter name and special constraint; CLR/native execution returns 42. A String instantiation rejects. All 76 C# groups and Raven's rebuilt native probe pass. Existing GenericParam/GenericParamConstraint and native encodings are unchanged.

Layered reader/writer direction (author clarification, 2026-10-01)

The intended write pipeline is builders → definitions → encoded metadata → PE. Builders are optional generation helpers over the shared definitions. Metadata encoding owns CLI tables/heaps, signatures, method bodies and explicit neoCLR extensions; the PE layer packages the result. The read path reverses these boundaries: PE extraction, metadata decoding and definition materialization. Builders may then wrap editable loaded definitions. Readers and writers should expose complementary responsibilities at these boundaries, rather than making the object model depend on a particular packaging writer.

This is the target architecture, not a claim that the separation is complete. Current AssemblyBuilder.WriteImage still combines metadata/body encoding and PE packaging; AssemblyDefinition reading returns bounded immutable snapshots. Native container handling also has its existing adapter path. No format change or new binary layer API is claimed by this record. The definition migration provides shared authoring state; extracting the encoding/packaging boundary and materializing editable loaded definitions remain work.

Integration priority after architecture checkpoint

Author direction, 2026-10-01: the current API is good enough to resume the working Raven/native case. Further object-model migration, builder naming and encoding/PE separation are deferred unless required by an observed integration blocker. This supersedes the earlier migration-first sequencing, not the architectural direction. The current blocker remains imported Optional<Order> value-category support; the reference-only import contract must not be widened by treating it as a class.

Imported value signatures (integration slice, 2026-10-01)

AssemblyBuilder.ImportReference(TypeDefinition, core) now admits public top-level value definitions in addition to reference classes/interfaces. Values must directly extend System.ValueType through an AssemblyRef matching the explicit dependency core identity. Enums, local/fake ValueType bases, nested/nonpublic declarations and constrained/variant generic definitions remain unsupported. ImportedTypeReference.IsValueType is immutable and participates in identity, interning consistency and generic substitution. Special constraint checks distinguish imported values from references.

CLI signatures encode imported values with VALUETYPE and GENERICINST VALUETYPE. The static method signature decoder accepts dependency-local value TypeDefs and rejects CLASS/VALUETYPE disagreement with the declaration. Cross-dependency TypeRef signatures, imported instance/constructor calls and generic declaring-owner member calls remain unsupported. Importing a type does not import its members or implement Raven unions.

Native format-5 signatures still use Named/Constructed types resolved by the loader. To retain the CLI category in metadata-only projection, the assembly manifest has an optional value_type_references array of canonical external native definition names. The writer emits it only for imported values. The reader bounds it to 4096 unique names, requires declared dependency scopes and restores value-category signatures in the PE projection. Native validation requires each listed name to resolve to a nonreference, noninterface loaded type, rejecting missing declarations/category mismatches.

This is a temporary native projection annotation for information represented directly in CLI signatures. It adds no opcode or runtime representation. Existing payloads without the field retain their reference-only import interpretation. Payloads containing it require the updated runtime; older strict readers reject the new manifest field. The metadata library owns emission/projection and neoCLR owns dependency validation. The future native indexed metadata reader/writer should encode the category directly in signatures, removing the need for this annotation.

C# tests (77 groups) cover cross-assembly nominal/generic value signatures, CLR factory/read and default/forward execution (42), projection category retention, category disagreement and explicit core rejection. --imported-value-integration <runtime> <fresh-directory> emits separate native library/consumer containers, verifies/runs (42), and checks that a reference-class substitution for an imported value rejects. Raven's dedicated consumer probe also returns 42 with imported returns, parameters, locals and forwarding. The unchanged collections sample advances to an unsupported lowered invocation; it does not execute yet.

Imported member dispatch and closed generic interfaces (2026-10-02)

These are development host C# APIs in NeoCLR.Metadata.Experimental.Model. They use the existing CLI/CIL format: HAS_THIS and VAR in signatures, TypeSpec parents for constructed MemberRefs and callvirt for interface/final virtual dispatch. Native format-5 uses its existing constructed-owner function references and interface relationships. No new opcode is introduced. Reuse the CLI/Cecil comparison and research above; the benefit is one exact imported contract for both writers, with a bounded supported subset instead of host reflection loading. The cost is explicit dependency registration and rejection of currently unsupported declarations.

Type/member Contract
AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) Also imports public nongeneric instance methods of public top-level reference classes/interfaces. Concrete class methods must be nonvirtual or final; interface methods must be abstract/virtual. Owners may be invariant, unconstrained generic reference types. Core/identity/MVID, access/category and scoped signature checks remain mandatory.
ImportedMethodReference.IsStatic : bool Whether the reference excludes a receiver.
ImportedMethodReference.IsInterfaceMethod : bool Whether the declaring contract is an interface.
ImportedMethodReference.RequiresVirtualDispatch : bool Whether Callvirt is required, including final virtual class members; Call is rejected for these references.
ImportedMethodReference.MakeConstructedReference(IEnumerable<SignatureType> declaringTypeArguments, IEnumerable<SignatureType>? methodArguments = null) Returns ImportedConstructedMethodReference. Copies arguments, requires exact arities and consumer ownership; caller VAR/MVAR scope is checked when emitted. Instance method generics remain unsupported; static generics may have method arguments.
ImportedConstructedMethodReference.Definition The consumer-owned open imported member.
ImportedConstructedMethodReference.DeclaringType Consumer-owned constructed ImportedTypeReference.
ImportedConstructedMethodReference.Signature Substituted MethodSignature, with declaring and method parameters replaced simultaneously.
ImportedConstructedMethodReference.MethodArguments Read-only copied method argument list.
MethodBuilder.Call(ImportedConstructedMethodReference) Emits a direct Call for a concrete/static contract.
MethodBuilder.CallVirtual(ImportedMethodReference) and CallVirtual(ImportedConstructedMethodReference) Emit Callvirt for an imported interface/final virtual contract.
MethodBuilder.Emit(OpCode, ImportedMethodReference) and Emit(OpCode, ImportedConstructedMethodReference) Raw typed operands retain the same ownership, dispatch and generic-scope checks as helpers. No unrestricted integer/token escape hatch.
InterfaceImplementation(TypeReference, IEnumerable<SignatureType>) Definition-owned relationship with copied arguments; attachment validates ownership and shape.
InterfaceImplementation.TypeArguments : IReadOnlyList<SignatureType> Empty for nongeneric relationships, copied ordered arguments for a construction.
TypeBuilder.AddInterfaceImplementation(GenericTypeInstance) Appends the same definition relationship. Supports root classes, including generic owners, implementing owned generic interfaces with inherited edges and declaring-type arguments.

Null inputs throw ArgumentNullException; invalid construction/ownership/opcodes throw ArgumentException (an invalid implementation owner throws InvalidOperationException). Unsupported imported declarations, signature bytes, identity conflicts, limits, missing public interface implementations and invalid body stacks throw InvalidDataException. Instructions retain the existing count limits. Generic arities are at most 32; constructed relationships are bounded to 256. The target interface must be in the same assembly as an authored implementation; imported dispatch references themselves can cross assemblies. Neither API infers implementation conformance from matching method names alone.

var imported = consumer.ImportReference(interfaceMethodDefinition, explicitCore);
var call = imported.MakeConstructedReference(new SignatureType[] { PrimitiveType.Int32 });
body.Call(factoryReference); // Returns exactly the imported constructed interface.
body.LoadConstant(42);
body.CallVirtual(call);
body.Return();

Readers preserve closed generic interface relationships in reference projections; older experimental host readers reject this expanded subset. The existing native runtime already supports these relationships. Imported constructors/value-instance members, generic instance methods, nonfinal virtual class slots, generic interface inheritance, cross-dependency TypeRef signatures and native System identity mapping remain outside this increment. ImportedInterfaceChecks executes a separately written library/consumer on CLR and neoCLR (42), checks native null-receiver failure, wrong arity/opcode/owner rejection and reference projection. Raven's corresponding probe executes constructed interface and final class calls (42); the unchanged collections sample advances to propagation-expression lowering.

Writable managed-reference parameters

SignatureType.ByReference(SignatureType elementType) creates a managed-reference parameter signature; SignatureType.ByReferenceElement returns its target or null. The target is a non-Void supported type, including vectors and scoped generic parameters. Null throws ArgumentNullException; Void, nested byrefs or exceeding the 16-level nesting bound throws ArgumentException. Ownership and generic scope are checked on use. Only method parameters admit this type: byref returns, fields, locals, array elements and generic arguments reject. ToString appends & to the target diagnostic name.

MethodSignature, owned and imported method calls, generic substitution and native CLI projection preserve BYREF. CLI uses ELEMENT_TYPE_BYREF in parameter signatures; native uses its existing ByRef type. The bounded static value/generic signature readers recognize byref primitive/vector/MVAR parameters; primitive-only readers continue to return false for those signatures. Out flags are emitted only for explicit OutParameters contracts described below; no In flag or readonly modifier is inferred.

Call consumes an initialized exact local address or a matching forwarded ref parameter. It cannot establish assignment for an uninitialized caller local. LoadArgument loads the reference; LoadObject/StoreObject (or raw Ldobj/Stobj) read/write the referenced value. Argument rebinding with Starg rejects; Initobj remains local-address-only. The body validator rejects mismatched targets, non-address operands and uninitialized ref calls when either writer runs. References cannot escape via results or value locals. This slice does not admit ref receiver methods or Raven out propagation calls. Explicit metadata out calls are described below.

ByReferenceChecks.cs demonstrates generic replacement and reference forwarding, with independent library/consumer execution from both CLI snapshots and native projections. Run --byref-integration <runtime> <fresh-output> for native binary verification and execution (42); the regular C# tests include positive and rejection checks.

Output parameter contracts

MethodSignature(SignatureType returnType, IEnumerable<SignatureType> parameterTypes, IEnumerable<string>? genericParameterNames = null, IEnumerable<int>? outParameters = null) accepts optional zero-based declared parameter indices (excluding the instance receiver). IReadOnlyList<int> OutParameters exposes a copied, sorted list. Every index must be unique, in bounds and designate a ByReference parameter; invalid or oversized lists throw ArgumentException. Omission means ordinary ref semantics. The distinction is a parameter contract, not an overload identity; methods cannot overload ref versus out. Interface implementations must match the declared out contract.

Callers may pass uninitialized local addresses to declared outputs. On normal return, those locals become definitely assigned. Ref inputs, including aliases of outputs, are checked before any output assignment is published. Callees cannot read an output before writing it and must assign every output on every normal return path; forwarding an output to another out parameter also establishes assignment. Ldobj/Stobj use the same parameter addresses as ref calls. Invalid flow raises InvalidDataException when writing either representation. Initobj still accepts only local addresses.

CLI output uses ordinary BYREF signatures plus Param Out flags. Snapshot signature readers and imports retain those flags in OutParameters. Native output uses the existing out_parameters function member, which runtime loading checks and execution enforces; no wire-format extension or runtime opcode is added. Native-to-CLI projection writes matching Param rows. Generic method/owner substitution retains output indices. C# definite-assignment is a language rule; the CLI flag alone does not prove an external body assigns its outputs. Imported contracts require a trusted/validated implementation; the metadata reader does not inspect method bodies.

OutParameterChecks.cs covers generic assignment, output forwarding, ordinary CLR Out reflection, native projection/import and library/consumer execution. Negative checks cover invalid indices, missing/partial assignment, reads before writes, interface contract mismatch and aliased ref/out preconditions. Run --out-integration <runtime> <fresh-output> for native binary verify/run (42). Conditional out_when_true, readonly/in contracts and Raven admission remain unsupported by this producer API.

Managed value receivers

TypeBuilder.AddInstanceMethod and attached instance MethodDefinition declarations admit value types as well as reference classes. On a value type, argument zero is an initialized managed reference to the exact open declaring type. Field reads/writes and typed LoadObject/StoreObject may use that receiver; field mutation affects caller storage. Static-type instance declarations and value constructors remain rejected. CLI uses ordinary instance method signatures with implicit byref this; native writes receiver_byref: true. Native readers require that flag for value instance methods and preserve it when creating a CLI reference assembly. No new opcode or format extension.

ImportedMethodReference.RequiresManagedReceiver is true for value instance members. ImportReference accepts public nongeneric nonvirtual or final concrete value methods, including invariant unconstrained generic owners; ordinary imported signature limits still apply. RequiresVirtualDispatch is false for these concrete value calls, including final virtual implementations. Use Call (or Emit(Call, reference)) with an initialized exact managed receiver; value Callvirt is rejected because constrained/boxed dispatch is not represented by this contract. Constructed imported references retain their value category and receiver requirement. No receiver flag is added to ordinary parameter lists.

Receiver preconditions are checked before publishing any out assignments. Passing an uninitialized receiver also as an output does not make the call valid. Mismatched or value-copy receivers and invalid field/indirect access fail on writing with InvalidDataException. Import/dispatch argument failures retain existing exceptions. ValueReceiverChecks.cs demonstrates separate library/consumer mutation and generic TryGet(out T), CLI/native projection and rejection cases. Run --value-receiver-integration <runtime> <fresh-output> for CLR and native verify/run 42. Raven source value declarations and constrained interface calls are not implied.

Literal terminal failure

MethodBuilder.Fail(string message) and Emit(OpCode.Fail, string message) append a terminal instruction with no stack operand or result. The body stack must be empty. The native writer emits the existing fault instruction: execution ends with a host Fault classified as UserFault, preserving the message. No guest catch/finally semantics or host-process abort is introduced. The executable CLI writer instead constructs and throws System.InvalidOperationException(message) using ordinary CLI metadata/CIL; CLR callers can catch it. This is an explicit target difference, not a claim that CLR exceptions and native faults are interchangeable. The CLI core identity must supply that standard exception type. Native reference projections keep their existing nonexecutable throwing stubs.

Messages follow Ldstr validation: null throws ArgumentNullException; unpaired UTF-16 surrogates or text exceeding 64 KiB UTF-8 throw ArgumentException; empty text is valid. Instruction limits throw InvalidDataException. Writers reject a nonempty failure stack, reachable fallthrough and unreachable instructions after failure. Out parameters need assignment only on normal returns; a terminal-only path need not assign them. Labels and branch joins retain ordinary flow validation. Definitions can use the same logical opcode/string operand through the existing body model. Dynamic diagnostics remain the runtime library's System.Panic(message) contract; this bounded builder instruction accepts a literal only.

Value and imported constructors

The existing TypeBuilder.AddConstructor overloads and authored .ctor definitions admit value types, including unconstrained generic owners. CLI emission uses ordinary instance constructor metadata/CIL without injecting an Object base call into a value constructor. Native emission uses the existing managed construction receiver. Every own field must be assigned on every normal return. Reading a field before its assignment, using the whole construction receiver through ldobj/stobj, passing it to ordinary calls or storing it elsewhere is rejected when writing. A terminal failure path need not complete initialization. Constructor chaining remains unsupported. These conservative producer restrictions preserve the runtime's construction contract; they are not a claim that every CLR-valid constructor body is admitted.

AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) now admits public constructors of supported top-level classes and value types. The definition must have the CLI special-name/runtime-special-name flags, a nonstatic/nonvirtual/nongeneric Void signature and no byref parameters. Type initializers, nested owners and nested nominal parameter types remain unsupported. Imports still require exact dependency/core identity and the native writer's naming contract.

ImportedMethodReference.IsConstructor identifies allocation references. MethodBuilder.NewObject(ImportedMethodReference) and NewObject(ImportedConstructedMethodReference) consume the substituted constructor arguments and push the resulting declaring reference or value. Raw Emit(OpCode.Newobj, reference) is equivalent. Null references throw ArgumentNullException; foreign references, wrong dispatch opcodes and uninstantiated/invalid generic scopes throw ArgumentException. Instruction limits and invalid stack/initialization flow fail with InvalidDataException. Call/Callvirt reject constructor operands. Existing RequiresManagedReceiver describes the value member's implicit receiver; Newobj supplies its construction address rather than requiring a caller-supplied initialized address.

Nested declarations

TypeDefinition.NestedTypes : IList<TypeDefinition> exposes immediate children. Loaded snapshots are read-only. An attached authored owner accepts detached children with an empty namespace, no generic parameters and CLI NestedPublic (2) or NestedAssembly (5) visibility. The enclosing owner must also be nongeneric. Ownership is immutable after attachment; duplicate names are scoped to the enclosing definition. Cycles, reattachment, generic nesting and depth beyond 16 fail with ArgumentException; adding to a detached owner fails with InvalidOperationException. Module.Types continues to enumerate every physical declaration, including nested types. DeclaringType and ToReference().Resolve() preserve the same authored definition identity.

TypeBuilder.AddNestedClass(string name, TypeVisibility visibility = Public) and AddNestedValueType(string name, TypeVisibility visibility = Public) attach definitions through that collection and return their builders. Internal maps to NestedAssembly. Neither helper synthesizes constructors. Existing AddConstructor and body APIs apply. These helpers reject duplicate/invalid names, generic owners, unsupported visibility and declaration/depth limits with ArgumentException.

CLI writers emit NestedClass rows and nested visibility. Native writers retain both explicit module-local declaring_type and matching source declaring_type_token; readers validate that they identify the same preceding owner before reconstructing the reference projection. Runtime loading/execution is tested with a nested value constructor (42), alongside CLR execution, duplicate short names under different owners, deep navigation and malformed ownership rejection. Imported nested types and captured generic owner parameters are not yet supported. Existing top-level identities remain unchanged.

Nested imports and generic children

TypeBuilder.AddNestedGenericValueType(string name, IEnumerable<string> parameters, TypeVisibility visibility = Public) adds a generic value child under a nongeneric owner. The name excludes the arity suffix; one to 32 unique parameter names are copied. Null parameters throw ArgumentNullException; invalid identity, arity, visibility or ownership throws ArgumentException. NestedTypes now also accepts corresponding manually created generic value definitions. Captured generic outer parameters remain unsupported.

ImportedTypeReference.DeclaringType exposes the immutable enclosing definition reference, or null. ImportReference accepts public nested class/value declarations under public nongeneric containers, retaining scope through equality, hashing and generic substitution. Parents may be static containers. CLI TypeRefs use enclosing TypeRef resolution scopes; native identity paths are deterministic and preserve all owners. Private/internal enclosing scopes, generic captured owners and unsupported base/core contracts reject with InvalidDataException. NewObject, Call and constructed imported methods retain the nested owner; their earlier stack and ownership checks still apply.

C# fixtures execute nested imported nongeneric/generic value and class constructors on both CLR and neoCLR (42). Native reference projection remaps owned types by declaration identity instead of namespace/name, preventing collisions between equal child short names.

Structural Function bodies

SignatureType.Function(MethodSignature signature) creates a structural callable type. SignatureType.FunctionSignature is null for other categories, otherwise exposes FunctionSignature.ParameterTypes, ReturnType and NoResult. Shape equality/hash use ordered parameter/result identities, including scoped generic parameters and nominal owners; target methods and parameter names do not participate. The signature is immutable. Up to sixteen value parameters are supported; Void means explicitly no stack result. Byref/out callback contracts, generic callback declarations and inhabited Void results are outside this initial slice. Generic enclosing method/type parameters can occur in shapes and are substituted recursively. Nesting is limited to sixteen levels. Null signatures throw ArgumentNullException; unsupported contracts throw ArgumentException.

FunctionBinding(SignatureType functionType, MethodBuilder target) checks a nongeneric static, final/nonvirtual reference-instance or abstract interface target against the exact shape. The overload FunctionBinding(SignatureType, ConstructedMethodReference) accepts an owned constructed generic class/interface method after exact signature substitution. ConstructedTarget returns that reference (null for the MethodBuilder overload); FunctionType and Target expose the shape and method definition. Constructors, uninstantiated generic methods, nonfinal virtual class methods and value receivers are rejected. FunctionBinding(SignatureType, GenericMethodInstance) accepts an owned generic method with all method arguments supplied. GenericTarget returns that instance, or null. Constructed owner references may also supply method arguments. Both forms validate the substituted shape, caller scopes and generic constraints before writing. Null arguments throw ArgumentNullException; incompatible signatures throw ArgumentException. Emission additionally validates output ownership and caller generic scopes. MethodBuilder.BindFunction(functionType, target) and Emit(OpCode.BindFunction, FunctionBinding) push a callable value; the target must belong to the output assembly. Instance binding consumes the object receiver already on the stack; static binding consumes no receiver. InvokeFunction(functionType) and Emit(OpCode.Callvirt, SignatureType) consume the Function receiver and ordered arguments, then push the result unless NoResult. Invalid operands, target kinds, ownership or scope throw ArgumentException, null operands ArgumentNullException. Instruction limits and invalid evaluation stacks fail with InvalidDataException (stack validation on write). Bound instance receivers retain shared object identity. Compiler-generated capture frames and external binding targets remain future work; ordinary imported methods can accept/return Function values.

Native output uses the runtime's structural Function shape, function.bind and ordinary instance Invoke. GetILGenerator().BindFunction supports definition, constructed-owner and generic-method target overloads; interface binding selects dispatch from the retained receiver. CLI output uses core-scoped Func/Action carriers with ldftn (ldvirtftn for interfaces)/newobj and callvirt, including generic signature variables on Invoke MemberRefs. This is a bridge representation; native Function identity is independent of a nominal delegate declaration. The imported-signature reader recognizes those carriers only in the explicit core scope. Ordinary CLI delegates retain their .NET behavior; native static/instance binding follows the existing Function runtime contract. This API does not expose native method pointers.

C# validation executes static bindings across an assembly boundary on CLR and native binary PE, including generic higher-order calls and a no-result callback (42). Exact shape equality, wrong results, wrong receivers and reference projection are checked. Raven consumes this transport for owned static and concrete instance method groups. Captured lambdas still require compiler-generated closure frames. Instance-binding C# tests execute two bindings against the same mutable receiver on CLR and NeoCLR and reject missing/wrong stack receivers before writing.

Concrete imported value overrides

AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) accepts public, nongeneric concrete instance overrides declared on imported value types. They consume an exact managed receiver and use direct Call; RequiresManagedReceiver is true and RequiresVirtualDispatch is false. This follows CLR's concrete value-call behavior, without boxing or reference dispatch. Abstract methods remain unsupported, as do nonfinal virtual/override methods on reference classes. The same explicit owner/core and signature validation applies. C# fixtures execute an actual CLR override and a matching native implementation emitted by the API, returning the expected string and 42. This does not add general class virtual dispatch or boxed value receivers.

Reference conversion bodies

MethodBuilder.CastReference(SignatureType target) and Emit(OpCode.Castclass, SignatureType) consume a reference and push the same object through the target reference signature. Targets are owned/imported nonstatic nominal reference types or vectors, including constructed generic reference types. Value types, managed addresses, Function shapes and unbounded generic parameters are not admitted. The operand must belong to the output assembly; invalid target/owner throws ArgumentException, null throws ArgumentNullException, and invalid source stacks or instruction limits produce InvalidDataException when validated. No boxing occurs. CLI output uses ECMA castclass; native output uses its existing castclass verifier and runtime contract, which may reject unsupported conversions. These methods do not promise general .NET downcast coverage. A C# fixture checks inherited interface dispatch through two implementations on CLR and neoCLR (42), and rejects value operands.

Explicit translated-library linkage

AssemblyBuilder.BindNativeLibrary(AssemblyDefinition reference, NativeLibraryDefinition implementation, AssemblyIdentity coreLibrary) registers one explicit declaration/implementation pair before importing any types or members from that dependency. All parameters are required (ArgumentNullException); the core must match the output core, the dependency must differ from the output, prior imports or a duplicate binding are rejected, and at most 256 dependencies are admitted (InvalidDataException). Registration returns no value. It does not execute or verify library bodies. Supply the implementation module separately when loading the consumer.

Subsequent ImportReference calls validate the selected public native declaration's name, arity, value/reference/interface category, instance/static shape, generic arity, parameter/result signatures, managed receiver and output contract. Unsupported or ambiguous matches fail with InvalidDataException. Translated names remove the CLI backtick arity suffix and join nesting with dots; this is an explicit temporary bridge, not a universal resolver or a general name-remapping API. Generic constraints and unsupported imported shapes retain their existing restrictions. Native interface members must have empty bodies. Static namespace carriers may use the translator's legacy value-like representation. Unused declarations are not individually validated.

CLI output preserves original AssemblyRef/TypeRef scopes. Native output uses the bound module name and exact revision when present (otherwise a name-only module reference), and records native_module_bindings/native_type_bindings in its manifest so the PE reference projection can recover the CLI identities. Readers reject undeclared scopes, duplicate aliases, invalid categories and cyclic declaring scopes. Older experimental runtimes do not understand these added manifest fields; use a matching compiler/library/ runtime bundle. No forwarding, dependency download or host assembly probing occurs.

Dependency-local TypeRefs, including local-core values extending a TypeDef System.ValueType, are accepted without an external resolver. Func/Action carriers also recognize the explicitly selected local core. Its inhabited nominal System.Void is mapped to native Void storage while remaining a nominal value in the CLI projection; CLI ELEMENT_TYPE_VOID still means no result. A CLI no-result call to an inhabited-Void native method emits a result discard, with branch offsets adjusted. This bridge does not erase an out parameter or add general CLI inhabited-void execution support.

The C# linkage fixture executes on CLR and neoCLR (42), tests versioned/unversioned bindings and malformed mappings, and provides the checked-in binary runtime fixture. LocalCoreSignatureChecks covers local nominal/core Function signatures and cyclic TypeRef rejection. The unchanged Raven collections application additionally exercises inhabited Void through Optional residual propagation.

The Rust host metadata model exposes metadata_origin::AssemblyMetadata's new native_module_bindings: Vec<NativeModuleBinding> and native_type_bindings: Vec<NativeTypeBinding> fields. Both default to empty on read and are omitted when empty on write. NativeModuleBinding has assembly: String, module: String, revision: Optional<String>; NativeTypeBinding has native_name, assembly, namespace, name (String), arity: usize, value_type: bool, and declaring: Optional<String>. They derive Debug, Clone, PartialEq, Eq, Serialize and Deserialize; unknown fields are rejected. Runtime admission checks declared scopes, text, duplicates and limits (256 modules, 4096 types, arity 32). These retain projection provenance; they do not authorize calls or override runtime resolution/access checks. Hosts constructing AssemblyMetadata literals must initialize the new vectors. These host-only APIs remain outside the guest RavenDoc assembly.

Constructed interface inheritance

TypeBuilder.AddBaseInterface(GenericTypeInstance baseInterface) adds an owned constructed generic base to an interface. Arguments may reference the declaring interface's type parameters. The definition graph remains authoritative: Definition.Interfaces retains both ordinary and constructed edges; BaseInterfaces lists only directly inherited nongeneric definitions. Null throws ArgumentNullException; a noninterface owner throws InvalidOperationException. Foreign/noninterface bases, duplicate edges, definition cycles, out-of-scope arguments and the existing 256-constructed-edge limit throw ArgumentException. Mutating a later declaration cannot introduce a cycle through a constructed edge.

Root classes, including generic owners, may implement inherited generic interfaces using the existing AddInterfaceImplementation(GenericTypeInstance) overload. Required methods are collected transitively with positional substitution before exact public instance implementation validation. Missing methods fail writing with InvalidDataException; inheritance expansion is bounded to 4096 distinct constructed contracts. This does not add variance, interface default bodies or MethodImpl mappings. CLI uses ordinary InterfaceImpl/TypeSpec signatures; native metadata uses constructed interface signatures with the existing runtime dispatch semantics. No new instruction or runtime metadata category is introduced.

MethodBuilder.CallVirtual(ConstructedMethodReference method) and Emit(OpCode.Callvirt, ConstructedMethodReference) dispatch owned constructed interface contracts. Constructors require Newobj, interface contracts require Callvirt, and other constructed methods retain Call. Null throws ArgumentNullException; invalid opcode, foreign target or invalid scope throws ArgumentException; instruction limits and invalid stacks fail with InvalidDataException. Both encodings preserve the same method signature and owner arguments. A C# fixture checks transitive positional substitution, CLI/native execution (42), PE reference projection, missing implementations, duplicate edges, cycles and invalid argument scopes.

Generic class interface implementations

TypeBuilder.AddInterfaceImplementation(TypeBuilder contract) now also accepts a nongeneric interface on a generic root class. The GenericTypeInstance overload accepts constructed interfaces whose arguments refer to that class's type parameters. The same relationships can be attached manually through Definition.Interfaces. Static/value/interface owners remain invalid implementation owners (InvalidOperationException); foreign/noninterface/duplicate edges and invalid owner or method parameter scopes remain ArgumentException. Existing edge limits apply.

Required inherited methods are substituted positionally and must have matching public instance implementations when writing (InvalidDataException otherwise). Stack checking also substitutes the actual generic receiver's arguments before permitting interface assignment or dispatch; it does not admit arbitrary generic conversions or variance. CLI output uses standard InterfaceImpl TypeSpecs and callvirt, and native metadata retains the same owner arguments for its existing runtime dispatch. No opcode changed.

C# tests execute Implementation<Unused,T> : Middle<T> : Root<T> with an Int32 Echo through Root<int> on CLR and neoCLR (42), reproject native metadata to CLI, and reject missing/mismatched implementations and out-of-scope type/method parameters. Raven's unchanged collection interfaces additionally execute with generic provider and iterator implementations, including constructor fields and inherited property/indexer calls. Loaded CLI TypeDefinition.Interfaces enumeration remains an explicit reader limitation; this change expands authored definitions and native round trips, not that reader view.

Checked uninitialized reservation

MethodBuilder.ReserveArray(SignatureType elementType) and Emit(OpCode.ReserveArray, SignatureType elementType) consume an Int32 length and push an ordinary vector of that exact element type. Supported scalar elements include caller-scoped type/method parameters. Null throws ArgumentNullException; unsupported Void/vector elements or invalid owner/parameter scope throw ArgumentException. Instruction limits and invalid stack shapes throw InvalidDataException on construction or writing as appropriate. OpCode.ReserveArray is appended to the public opcode enum.

This is a native-only extension. Native writing encodes existing array.reserve, and PE/#Neo loading retains checked uninitialized slots. Stores publish typed values; direct or addressed reads before publication fault in the runtime. Negative lengths and runtime allocation limits retain the existing array-reservation checks. NewArray/Newarr keep ordinary default initialization. See the storage contract.

AssemblyBuilder.Write() (and executable CLI writing through definitions) rejects a body containing reservation with InvalidDataException: CLI newarr is not an equivalent encoding. Native container reference projections remain available and do not promise executable CLI bodies. No native format version, runtime opcode or guest public API changes are required. This host-only builder API is covered by this manual reference, not the guest RavenDoc assembly.

C# checks cover generic raw emission, native verification/execution (stored slot 42, unread slot fault), projection loading, executable CLI refusal, invalid element and parameter scope, and an invalid length stack type. Raven separately tests the matched explicit authoring-seed mapping and its default-disabled configuration.

Native assembly-level-function dependency binding

BindNativeLibrary also recognizes public, nongeneric, abstract sealed top-level CLI containers carrying the exact configured core's System.Runtime.CompilerServices.TopLevelAttribute. The marker must have a parameterless constructor and no named arguments. Public static concrete methods bind to ownerless native functions named namespace.method, with existing arity, parameter, result and access validation. Container spelling is irrelevant. CLI output preserves the container reference; native output uses the bound function. Unmarked or incorrectly scoped containers do not receive namespace treatment. Raw CLI global-method imports remain unsupported. This is temporary CLI bridge interpretation, not a general public custom-attribute API or native semantic importer.

Direct native declaration reading

AssemblyDefinition.ReadNativeAssembly(ReadOnlySpan<byte> image) reads API-produced PE/#Neo schema-1/2 containers into the existing definition model. This first profile admits nongeneric assembly-level functions and fieldless top-level classes with Int32, Int64, Boolean, String or no-result method signatures. It rejects other types and unsupported signatures with InvalidDataException rather than silently returning a partial assembly. Input/container limits and required-schema/binding checks still apply. No dependency is loaded, CLI assembly generated, method body translated or host reflection used.

AssemblyDefinition.IsNative identifies snapshots populated from authoritative native metadata. Identity and MainModule.AssemblyReferences retain exact declared scopes. MainModule.Functions/Methods contain the same canonical MethodDefinition objects, including namespace ownership via MethodDefinition.Namespace. MetadataToken and EntryPointToken retain validated native origin identifiers, local to the module. MainModule.Mvid is Guid.Empty because the native manifest declares no MVID; consumers must not use it alone as a snapshot identity. Profile is null for this execution profile.

MethodDefinition.TryGetSignature(out MethodSignature? decoded) returns an immutable logical signature for native functions, authored methods, bounded nongeneric CLI instance/static methods (including nominal TypeDef/TypeRef parameters/results and single vectors), and the existing bounded static CLI generic value profile. Nongeneric nominal identities remain snapshot-owned references; dependencies are resolved only by an explicit introspection catalog. Generic constructions, unscoped owner parameters, custom modifiers and unsupported calling conventions still return false. Invalid local nominal token/category combinations also return false. The older static-only signature helpers retain their original narrower contract. Void means no result, not an inhabited value. Existing static primitive/value signature helpers also recognize these native functions. GetSignature throws NotSupportedException for native methods; there is no CLI blob. Body remains unsupported for loaded methods; no empty executable body is fabricated.

Write returns a fresh copy of the original complete PE, preserving opaque bodies. Loaded mutation, builder attachment and native rewriting remain unsupported. The existing IAssemblyResolver/AssemblyReference.Resolve contract accepts these snapshots and rechecks exact identity, including version; missing/mismatched dependencies fail. It supplies metadata definitions, not runtime reflection objects.

var assembly = AssemblyDefinition.ReadNativeAssembly(File.ReadAllBytes("Library.dll"));
foreach (var function in assembly.MainModule.Functions) {
    if (function.TryGetSignature(out var signature)) {
        Console.WriteLine($"{function.Namespace}.{function.Name}: {signature!.ParameterTypes.Count} parameters");
    }
}

Raven primitive function loading and call imports are implemented in the bounded development path below. Instance type/member materialization and structural signatures remain pending. Standalone translated System inventory is not admitted by this PE function-only entry point. Existing CLI readers/writers remain unchanged. These host C# APIs are covered here rather than the guest RavenDoc selection.

Native callable imports

AssemblyBuilder.ImportReference(MethodDefinition definition, AssemblyIdentity dependencyCoreLibrary) now accepts primitive nongeneric native assembly-level-function definitions obtained from ReadNativeAssembly. It returns the existing immutable ImportedMethodReference; Call and raw call operands use the same native reference encoding. Namespace, overload signature and exact dependency identity are retained. No producer body is copied.

The explicit dependency core must match the output core. Existing identity/resource limits apply. InvalidDataException reports unsupported contracts, incompatible cores or conflicting snapshots. Native snapshots are compared by a cached SHA-256 of the complete owned PE, since their Mvid is empty; identical rereads share an import, while byte-different images under one identity are rejected even if logically equivalent. CLI snapshots retain their MVID comparison. Snapshot fingerprints are not public or persistent assembly identity and do not change the encoded metadata format.

var dependency = AssemblyDefinition.ReadNativeAssembly(File.ReadAllBytes("Library.dll"));
var target = dependency.MainModule.Functions.Single(f => f.Name == "Twice");
var imported = output.ImportReference(target, explicitCoreIdentity);
var main = output.AddFunction("Main");
main.LoadConstant(21);
main.Call(imported);
main.Return();
output.EntryPoint = main;

Global/native namespace calls support native emission, not ordinary CLI output. Import does not perform source accessibility checking or discover/load dependencies; Raven performs semantic access checks and neoCLR resolves explicit runtime modules. Generic/richer-signature native callable imports remain outside this read profile. These host C# APIs continue to use this manual reference instead of the guest RavenDoc inventory.

Direct native static types

ReadNativeAssembly additionally admits fieldless, nongeneric top-level static classes with primitive static method signatures. Module.Types contains canonical TypeDefinition objects; each TypeDefinition.Methods member links back through DeclaringType. These members do not appear in Module.Functions. Public/internal type visibility and public/internal/private member visibility are preserved using the existing CLI-shaped attributes. Type tokens retain validated native origin tokens (the first is 0x02000002). TypeReference.Resolve returns the same owned definition. Loaded collections remain read-only and Write preserves the original complete image.

AssemblyBuilder.ImportReference accepts these primitive static methods through the existing callable overload. Value/interface/nested/generic types, fields, properties and nonprimitive signatures still reject the entire read with InvalidDataException; no partial type inventory is silently exposed. This adds no new encoding or public API surface. Compared with .NET metadata, ownership and access flags use the same shape; the supported native declaration profile remains narrower.

Direct native instance classes

ReadNativeAssembly also admits fieldless nongeneric top-level instance classes. Existing TypeDefinition.Attributes retains the native class's nonabstract/nonsealed category; MethodDefinition.IsStatic reflects receiver presence. Constructor definitions use .ctor, SpecialName/RTSpecialName flags and a no-result logical signature. The explicit signature parameters exclude the receiver. TryGetSignature accepts these declarations, while all TryGetStatic* signature helpers reject instance methods and constructors.

ImportReference(TypeDefinition, core) admits the public instance-class identity for locals/receivers. ImportReference(MethodDefinition, core) accepts public primitive instance methods and constructors through its existing contract. ImportedMethodReference IsConstructor/IsStatic and its declaring identity govern NewObject/Call emission; no reflection object or CLI signature blob is synthesized. Existing core, exact identity, snapshot and accessibility restrictions remain. Raven performs source access checks.

The loaded definition graph remains immutable. Fields/properties, value/interface/ nested/generic classes and nominal parameter/result signatures are rejected by the current direct reader. Existing writer/runtime support is broader than this read profile. No additional guest API or RavenDoc type is introduced; this manual covers the host APIs.

Direct native primitive fields

ReadNativeAssembly now also admits Int32, Int64, Boolean and String instance fields on nongeneric top-level classes. TypeDefinition.Fields and Module.Fields expose canonical FieldDefinition instances; GetFieldDefinition(originToken) returns that same instance. DeclaringType, name, access and InitOnly/readonly flags retain their native contracts. Field tokens retain validated origin identities, starting at 0x04000001.

FieldDefinition.TryGetPrimitiveType(out PrimitiveType type) recognizes these native fields without inventing CLI signature bytes. GetSignature throws NotSupportedException for native fields. FieldType remains the authored-only signature property (null for loaded declarations); use the existing primitive query in this bounded read profile. Loaded field names and collections remain immutable, and Write preserves the input PE. Nominal/vector/structural field signatures still reject the entire direct read.

Raven exposes these native fields as compiler symbols, retaining type/access/readonly information. A native library's constructor and instance methods can initialize/read its own fields using existing source emission. Direct consumer field emission across the assembly boundary is not implemented: it reports NEOMETA001 and leaves output empty. The stateful method-call consumer is tested separately and returns 42. No guest API, encoded layout change or new public host member is introduced by this reader slice.

Imported primitive field operands

AssemblyBuilder.ImportReference(FieldDefinition definition, AssemblyIdentity dependencyCoreLibrary) returns an interned ImportedFieldReference for a public Int32/Int64/Boolean/String instance field on a public nongeneric top-level reference class. The owner must contain only instance fields; constructed/value/interface/static owners and translated layout bindings are unsupported. Null arguments throw ArgumentNullException. Unsupported contracts, core/snapshot conflicts and the 4096-import limit throw InvalidDataException. Existing exact type identity and snapshot checks apply before a cached reference is reused. Authored/detached mutable field definitions reject; read an immutable snapshot first.

ImportedFieldReference exposes read-only Owner (consuming AssemblyBuilder), DeclaringType (ImportedTypeReference), Name, FieldType (primitive SignatureType) and IsReadOnly. It owns no mutable producer graph or executable body. Native field ordinals remain internal.

MethodBuilder.LoadField(ImportedFieldReference), StoreField(ImportedFieldReference) and Emit(OpCode, ImportedFieldReference) support Ldfld/Stfld. Null operands throw ArgumentNullException; wrong opcodes/foreign output ownership throw ArgumentException. Write validates the exact receiver, primitive value stack types and readonly restriction; violations throw InvalidDataException. Imported readonly fields may be loaded but never stored by the external consumer, including its constructors.

CLI writing emits a TypeRef-scoped field MemberRef and ordinary ldfld/stfld instructions. Native writing requires an imported native definition snapshot so the field ordinal is established by validated native metadata. A CLI field snapshot can emit CLI but native writing rejects it: no CLI-to-native layout equivalence is guessed. Supply the exact matching native library artifact to the runtime. The existing native field opcode format is unchanged.

var library = AssemblyDefinition.ReadNativeAssembly(File.ReadAllBytes("Library.dll"));
var field = library.MainModule.Types.Single(t => t.Name == "Calculator")
    .Fields.Single(f => f.Name == "Visible");
var imported = output.ImportReference(field, explicitCoreIdentity);
body.LoadLocal(receiver); // local uses imported.DeclaringType
body.LoadConstant(42);
body.StoreField(imported);
body.LoadLocal(receiver);
body.Emit(OpCode.Ldfld, imported);

C# contract tests execute CLI field accesses on the CLR from both CLI and native read-model inputs, and cover readonly/receiver/opcode/ownership/core/snapshot rejection. Raven consumers execute direct native field stores and loads across assemblies (42). These host C# APIs use this manual reference and remain outside guest RavenDoc selection.

Native local nominal signatures

SignatureType.ReferencedType { get; } returns TypeReference?: a nominal reference owned by a loaded definition snapshot, or null for other signature categories. For the direct native reader's current profile, ReferencedType.Resolve() requires no resolver and returns the canonical local TypeDefinition. ClassType and ImportedType remain null for this category; no mutable builder is retained. ToString() provides a diagnostic namespace/name, not serialized identity. The getter performs no code loading.

AssemblyDefinition.ReadNativeAssembly and MethodDefinition.TryGetSignature support nongeneric local root class parameter/result types as well as primitives, on namespace functions, class methods and constructors. The native format and opaque Write roundtrip are unchanged. Cross-dependency, generic, interface/value, array/byref signature categories, nominal fields and properties remain outside this read profile and throw InvalidDataException.

AssemblyBuilder.ImportReference(MethodDefinition, core) imports each referenced local class through the existing exact identity/snapshot/core checks and produces output-owned ImportedTypeReference signature operands. Existing public-type/access restrictions apply; unsupported imports throw InvalidDataException. Passing a loaded nominal SignatureType directly to a builder definition throws ArgumentException: import its declaring method or resolve and explicitly import its type first. This separation prevents a loaded snapshot from acquiring an output builder owner.

The static Int32, primitive and primitive-vector signature helpers continue to return false for nominal signatures. Use TryGetSignature to inspect the richer native profile. C# tests read both native container variants and execute imported factory/instance calls on the CLR; Raven tests compile and execute factories, nominal function/method signatures and constructor arguments in neoCLR. These are host development APIs, not guest APIs.

Native local nominal fields

FieldDefinition.TryGetSignature(out SignatureType? type) returns true for authored field types, direct native primitive/local class fields and primitive CLI field blobs. It returns false with null for other loaded CLI signatures; unsupported does not mean absent. No body or dependency is loaded. A native nominal signature's ReferencedType resolves to its snapshot's canonical TypeDefinition, shared with method signature types. Forward/cyclic local references are supported. Loaded FieldType remains the existing authored-only property; use TryGetSignature for a loaded field's logical type.

ReadNativeAssembly now admits fields referring to local nongeneric root classes. Unsupported external, array, generic, value/interface field shapes still reject the read with InvalidDataException. Native GetSignature still throws NotSupportedException because no CLI blob exists; TryGetPrimitiveType returns false/Void for nominal fields. Loaded declarations remain immutable and Write still copies the original native image.

AssemblyBuilder.ImportReference(FieldDefinition, core) additionally accepts these native nominal fields when both the owner and referenced storage type satisfy existing public class import rules. ImportedFieldReference.FieldType contains an output-owned ImportedTypeReference signature. LoadField, StoreField and raw Ldfld/Stfld operands use the existing exact receiver/value checks and readonly-store rejection. Null/foreign operands retain their existing errors; unsupported signatures/core/snapshot/layout contracts throw InvalidDataException. CLI writing emits a nominal field MemberRef; native writing uses the existing validated ordinal. CLI nominal field decoding/import remains outside this bounded profile. No PE/#Neo schema or opcode change is introduced.

C# tests cover forward/cyclic references, field/method signature identity, both native containers, immutable fields, incorrect primitive/nominal stores and readonly stores. They execute the emitted equivalent on .NET (42); Raven consumers execute replacement, nested mutation and original-object independence in neoCLR (42).

External native nominal signatures

ReadNativeAssembly now admits nongeneric top-level reference classes from declared native dependencies in method/function/constructor and field signatures. The reader copies their exact assembly identity, namespace and name into TypeReference rows in ModuleDefinition.TypeReferences. ReferencedType points to that same immutable reference. Native TypeRef tokens are reader-assigned, module-local identifiers, not claimed CLI rows or native origin tokens. ResolutionScopeToken identifies the declared AssemblyRef. Read/inspection does not load dependencies or resolve types. Write preserves the original PE/#Neo image and introduces no format or instruction change.

TypeReference.Resolve(IAssemblyResolver? resolver = null) retains its existing contract: external references require an explicit resolver returning an exact-identity snapshot; missing/wrong dependencies or missing/ambiguous types throw InvalidDataException. No filesystem probing, simple-name fallback or runtime reflection loading occurs. Local references still resolve without a resolver.

New overloads:

ImportedMethodReference AssemblyBuilder.ImportReference(
    MethodDefinition definition, AssemblyIdentity dependencyCoreLibrary,
    IAssemblyResolver? resolver);
ImportedFieldReference AssemblyBuilder.ImportReference(
    FieldDefinition definition, AssemblyIdentity dependencyCoreLibrary,
    IAssemblyResolver? resolver);

These import native nominal signature types through the supplied resolver into the output's existing interned nominal references. All resolved types must be public, nongeneric top-level reference classes, and the supplied core contract applies to all of them. Exact snapshot/core checks remain in force. Existing two-argument overloads remain available and behave as before; external native signatures require a resolver. Null definition/core throws ArgumentNullException; a null resolver is permitted for local-only contracts. Missing/mismatched/unsupported dependencies or conflicting snapshots throw InvalidDataException. Resolver exceptions retain host meaning. Primitive helpers continue to reject nominal signatures. CLI cross-dependency signature decoding is not expanded by these overloads.

C# tests inspect both native containers, check scoped reference/field/method identity, reject missing resolver/version/type/snapshot conflicts, and execute a three-assembly consumer on .NET (42). Raven compiles the same dependency shape and executes it in neoCLR. Generic, constructed, value/interface and array signature profiles remain unsupported.

Native vector signatures

ReadNativeAssembly, MethodDefinition.TryGetSignature and FieldDefinition.TryGetSignature admit one-dimensional zero-based vectors of supported primitives or nongeneric root reference classes. SignatureType.ArrayElement retains the primitive kind or immutable nominal reference; external class elements use the existing explicit resolver contract. Field and method signatures share the same nominal element identity. Opaque Write still copies the original image. No format or public API signature change is introduced.

Method/field ImportReference overloads recursively map array elements into output-owned signatures and retain exact dependency/snapshot checks. Loaded nominal array signatures must be imported before builder use; using one directly throws ArgumentException. Array operands continue to use existing exact element-type validation. Wrong array arguments or field stores throw InvalidDataException on write. No covariance, jagged, multidimensional, generic, value/interface element or byref-array support is added. Unsupported native declaration shapes still reject the entire read.

TryGetStaticValueSignature recognizes native primitive vectors, matching its existing bounded CLI profile; nominal vectors return false. TryGetStaticPrimitiveSignature and TryGetPrimitiveType continue to reject all vectors. Use the logical signature APIs to inspect nominal arrays. CLI field decoding remains limited to its existing primitive profile; native array field imports can emit either CLI MemberRefs or native ordinals.

C# checks cover both native containers, primitive vector helper behavior, nominal element identity, field/method signature equality, wrong-element arguments/stores and .NET execution of native array imports (42). Raven's three-assembly consumer stores an external-class array in a field, replaces an element through an alias and passes a primitive array across the same boundary; neoCLR returns 42.

Native non-indexed properties

ReadNativeAssembly now materializes non-indexed properties on the supported root class profile. ModuleDefinition.Properties, TypeDefinition.Properties and GetPropertyDefinition return the same snapshot-owned PropertyDefinition objects. DeclaringType, GetMethod and SetMethod refer to canonical definitions; accessor visibility and staticness are preserved, with SpecialName on accessor methods. MetadataToken is the validated native property origin token. Missing accessors remain null, including read-only and write-only properties; OtherMethods is empty.

public bool TryGetSignature(out SignatureType? type, out bool isStatic);

PropertyDefinition.TryGetSignature returns the logical property value type and staticness for supported native properties, authored non-indexed properties and primitive non-indexed CLI properties. It returns false, null and false for other loaded CLI signatures and indexers. Native types include supported primitives, local/external nominal classes and their vectors. References belong to the immutable snapshot; dependencies resolve explicitly through the existing resolver contract. GetSignature throws NotSupportedException for native properties because they have no CLI blob. PropertyType and ParameterTypes remain authored-only APIs; use the logical reader for loaded native properties. TryGetPrimitiveSignature recognizes native primitive properties and rejects nominal/vector properties with Void/false outputs.

Import the canonical accessor methods through AssemblyBuilder.ImportReference to emit property calls; properties themselves are associations rather than CIL call operands. Existing exact identity, resolver and snapshot checks apply. An unchanged native assembly still writes its original bytes. Indexed properties, generic/value/interface owners and unsupported signatures fail the whole direct read with InvalidDataException. No property schema or runtime opcode changes are made. C# checks cover both containers, ownership, signatures, static/read-only/write-only accessors, CLR accessor execution, opaque roundtrip and indexer rejection. Raven consumes separately compiled native properties through the same accessor definitions.

Native indexed property signatures

ReadNativeAssembly now also admits indexed properties in the existing supported root-class profile. Ordered index types are immutable signature shapes, with the same primitive/nominal/vector support and exact dependency resolution as value types. Accessor associations retain canonical method identity and their existing visibility.

public bool TryGetSignature(out SignatureType? type,
    out IReadOnlyList<SignatureType> parameters, out bool isStatic);

The new PropertyDefinition overload returns the value type, ordered index parameters (excluding the setter value), and accessor staticness. It supports authored/native properties, including getter-only and setter-only indexers, and the existing bounded non-indexed primitive CLI profile. On failure outputs are null, an empty list and false. The returned parameter collection is read-only. It does not resolve dependencies or materialize bodies. The existing two-output overload and TryGetPrimitiveSignature continue to reject indexers. PropertyType/ParameterTypes remain authored-only; native GetSignature still throws NotSupportedException rather than inventing a CLI blob.

C# tests cover both containers, authored/native signatures, immutable parameter lists, setter-value exclusion, accessor identity, byte-preserving roundtrip and CLR execution of imported indexer methods. Raven now consumes setter-only indexers as well as read/write overloads through the same property parameter contract. Source reads and compound assignments require an accessible getter. No CLI/native property encoding or runtime opcode changes.

Direct native interface definitions

ReadNativeAssembly now admits nongeneric top-level interfaces and local interface inheritance/root-class implementation relationships. TypeDefinition.Attributes retain CLI Interface/Abstract flags; interface methods retain Abstract/Virtual/NewSlot flags. Existing property/accessor and primitive/nominal/vector signature APIs apply.

TypeDefinition.Interfaces returns a cached, read-only IList<InterfaceImplementation> for native snapshots, including an empty list for owners with no contracts. Each relationship has the exact DeclaringType and a reference resolving to the canonical local interface definition; TypeArguments is empty in this profile. Mutations throw NotSupportedException. Authored collections remain append-only; loaded CLI relationship materialization still throws NotSupportedException. Concurrent reads share relationship identity. Unchanged native images still write their original bytes.

AssemblyBuilder.ImportReference now accepts interface-valued native signatures. Imported abstract interface methods require CallVirtual. Body validation admits native class/interface-to-interface conversions only when exact imported snapshots prove an inheritance/implementation path; unrelated interfaces still reject. This is cached nominal conformance, not duck typing, generic variance or an unrestricted reference cast. Existing core/identity/snapshot checks apply. Generic/value/nested owners, external interface implementation edges and loaded CLI relationship decoding remain unsupported.

C# tests cover both native containers, canonical immutable relationships, abstract flags, byte-preserving roundtrip, unrelated-interface rejection and CLR execution of accessors imported from native definitions. Raven separately compiles interface factories and a consumer; neoCLR executes inherited method/property dispatch (42).

Interface-valued fields and arrays are also covered by C# import/emission tests. A concrete native class with a proven local implementation path can be stored in an imported interface field or exact-interface array and dispatched on CLR. Raven's three-assembly consumer verifies equivalent native storage and alias behavior. These use existing FieldDefinition and MethodDefinition signature/import APIs; no new public API or array covariance rule is introduced.

Direct native static generic methods (2026-10-02 development)

AssemblyDefinition.ReadNativeAssembly now also admits unconstrained static generic methods and assembly-level functions on nongeneric owners. MethodDefinition.GenericArity and TryGetSignature preserve parameter names, positional SignatureType.MethodParameter references and their one-dimensional vectors. TryGetStaticGenericValueSignature recognizes the primitive/parameter/vector subset; nongeneric helpers reject even unused generic parameters. GetSignature still rejects native CLI-blob requests.

AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) retains this signature; ImportedMethodReference.MakeGenericInstance uses the existing arity and consumer-ownership checks. MethodBuilder.Call accepts that instantiated reference. Static methods can emit CLI MemberRef/MethodSpec or native generic calls; namespace functions remain native-only imports. Both native container schemas are covered.

Generic owners, generic instance methods, constraints, byrefs and nested vectors remain outside this direct-reading profile and throw InvalidDataException. Loaded definitions are immutable; Write preserves the original image. Raven's native symbol layer now consumes this same static generic profile through method-owned parameters and shared constructed-method substitution. Native parameter names must also satisfy runtime slot-name rules; the existing writer can accept reserved names such as Value that runtime verification rejects. This writer validation mismatch remains a follow-up, not an accepted runtime contract.

Direct native generic root classes (2026-10-02 development)

AssemblyDefinition.ReadNativeAssembly now also admits unconstrained generic root classes with bounded members. TypeDefinition.GenericArity and the read-only GenericParameterNames retain the metadata arity/name suffix and declared parameter names. CLI snapshots still return null for GenericParameterNames. SpecialConstraints and GenericConstraints return empty read-only views for the supported native profile; constrained native declarations remain rejected, not silently stripped.

MethodDefinition.TryGetSignature, FieldDefinition.TryGetSignature and property signature queries preserve SignatureType.TypeParameter(ordinal) and its vectors. AssemblyBuilder.ImportReference(TypeDefinition, core) creates the open reference; MakeGenericInstance constructs it. Imported constructors and methods use the existing ImportedMethodReference.MakeConstructedReference API and shared substitution. They emit CLI or native calls without projecting native definitions to CLI metadata.

The bounded profile does not yet materialize constructed nominal signatures such as Box<int> in a declaration, generic interface/static owners or generic inheritance. Native generic constraints, nested/value owners and instance generic methods still reject. Direct imported fields on constructed owners remain unsupported; use supported methods/properties. Both container schemas execute Box<int> construction, Set and Get on neoCLR; the equivalent CLI consumer executes on CLR (42).

ReferencedGenericType (development 2026-10-02)

Namespace: NeoCLR.Metadata.Experimental.Model. The new read-only SignatureType.ReferencedGenericInstance property returns a ReferencedGenericType for loaded constructed signatures such as Box<int>; otherwise null. Its public members:

  • TypeReference Definition: canonical snapshot-scoped generic definition reference.
  • IReadOnlyList<SignatureType> TypeArguments: copied, immutable arguments in ordinal order.
  • Equals(ReferencedGenericType?) / Equals(object?): definition reference identity plus structural ordered argument equality; null and other categories are unequal.
  • GetHashCode(): agrees with that equality; it is not a stable serialized identity.
  • ToString(): diagnostic display, not a serialized type name.

ReadNativeAssembly retains local closed generic root-class constructions in the supported field/property/method signature categories, including vectors. Arguments can include bounded primitive, nominal, vector and nested closed construction signatures. Scoped parameters inside a local construction (Box<T>) are now retained, including method and owner parameters and vectors of constructions. Ordinals are validated against the declaring scope by the native reader. External generic constructions retain exact assembly-scoped definition references and ordered arguments too. Resolving/importing them requires the explicit resolver overload, just like external nongeneric signatures. Missing or wrong-version dependencies throw InvalidDataException. Constraints and generic inheritance remain unsupported.

Loaded construction signatures are not builder operands: using one directly in an authored method fails ownership validation with ArgumentException. Import the containing declaration using AssemblyBuilder.ImportReference; that recursively imports the owner and arguments into output-owned references. Existing CLI/native constructed-call encoding is reused. No synthetic CLI blobs or reflection types are introduced.

Authored function references

AssemblyBuilder.CreateFunctionReference(AssemblyIdentity dependency, AssemblyIdentity dependencyCoreLibrary, string artifactSha256, string namespace, string name, MethodSignature signature, IReadOnlyList<GenericMethodTypeConstraint>? interfaceBounds = null) -> ImportedMethodReference creates a native assembly-level function reference from resolved values. It needs no reader, MethodDefinition or resolver. The returned reference is owned by the output builder; matching name/parameter/arity contracts are interned. Use Call or MakeGenericInstance on the result through the existing emission API.

The dependency must be unsigned, distinct from the output, and use the same explicit core identity. The digest must contain 64 hexadecimal SHA-256 digits; its comparison is case-insensitive. It identifies the host-selected native image for conflict checks within the output, not an encoded runtime integrity guarantee. The caller is responsible for the truth and completeness of the contract and for supplying the matching runtime artifact. No image loading, accessibility checking or dependency verification occurs.

Supported signatures contain Int32, Int64, Boolean, String, a Void result, method-owned generic parameters, output-owned external top-level nominal signatures (reference and value types, including closed/open constructions), and single-dimensional vectors of supported non-Void scalars. Construction arguments are checked recursively, including method-parameter scope and output ownership. Nested types, owner parameters, byrefs and out parameters are rejected. The caller must supply the nominal declaration facts; this does not import inheritance or interface conversion information. Function names and namespaces obey the existing authored declaration rules. A required null argument throws ArgumentNullException; malformed digests, names/namespaces or parameter scope throw ArgumentException. Unsupported contracts, incompatible core/identity, snapshot conflicts, inconsistent result signatures and resource limits throw InvalidDataException. Native output retains the existing format-5 name/signature linking contract; ordinary CLI output rejects references to assembly-level functions.

var signature = new MethodSignature(PrimitiveType.Int32, [PrimitiveType.Int32]);
var call = output.CreateFunctionReference(dependencyIdentity, coreIdentity,
    dependencyImageSha256, "Example", "Identity", signature);
main.LoadConstant(42);
main.Call(call);
main.Return();

Optional interfaceBounds preserve nominal generic constraints on assembly-level functions (development, 2026-10-16). Each bound must name an output-owned, unconstructed nongeneric authored interface, with a valid method parameter ordinal. The list is copied; duplicates, null entries, foreign bounds and more than 128 entries throw ArgumentException. Conflicting bounds for an interned callable throw InvalidDataException. MakeGenericInstance validates declared nominal membership; operator shape alone does not satisfy a bound. The host must author the relevant interface conversions as well as the function signature. The same validation is shared with CreateMethodReference. Primitive arguments use the consuming output's explicitly selected nominal scalar owner and declared conformance, including inherited interfaces. Missing owner or membership is rejected. This adds no CLI representation or runtime opcode.

The C# AuthoredFunctionReferenceChecks exercises creation without a reader and rejection contracts. NativeGenericMethodChecks reconstructs a generic vector reference from values and executes it in both native containers. The separate library IILGenerator API remains planned; the snippet uses the current MethodBuilder operations.

Authored type references

AssemblyBuilder.CreateTypeReference(AssemblyIdentity dependency, AssemblyIdentity dependencyCoreLibrary, string artifactSha256, string namespace, string name, int genericArity = 0) -> ImportedTypeReference authors an output-owned public top-level reference-class identity from resolved values, without a reader or resolver. name is the metadata name: a generic definition includes its backtick arity suffix. Arity is 0–32. Parameters are asserted invariant and unconstrained. Construct an open generic reference with MakeGenericInstance before using it in a signature. Matching references are interned, including subsequent imports from the same snapshot.

Identity/core/digest rules match CreateFunctionReference: unsigned external identity, matching explicit core, and 64 hexadecimal SHA-256 digits. This does not verify the image, accessibility, members or generic constraints. It carries no inheritance or interface conversion information; value/nested/interface declarations are outside this API's contract. The digest detects conflicting selected snapshots within the output, not runtime integrity. Mixed reader imports and authored references share the checks.

Null arguments throw ArgumentNullException; a malformed digest throws ArgumentException. Unsupported identity, metadata name/arity, core mismatch, snapshot conflict and resource limits throw InvalidDataException. The current limits are 4,096 nominal references and 256 dependency identities. Returned construction arguments are copied and checked against the consuming output's scope by MakeGenericInstance.

var box = output.CreateTypeReference(dependencyIdentity, coreIdentity,
    dependencyImageSha256, "Example", "Box`1", 1);
SignatureType integerBox = box.MakeGenericInstance(PrimitiveType.Int32);

AuthoredFunctionReferenceChecks covers reader-free nominal identity, interning, argument copying and negative contracts. NativeGenericOwnerChecks uses an authored Box reference alongside imported members, checking canonical identity and execution on CLR and both native containers. This does not imply that member references are reader-independent.

Authored method references

AssemblyBuilder.CreateMethodReference(ImportedTypeReference declaringType, string name, MethodSignature signature, bool isStatic = false, bool isOverride = false) -> ImportedMethodReference authors a public concrete nonvirtual root-class member contract without a reader definition. The declaring type must be an output-owned, top-level reference-class definition whose dependency/core/artifact contract has already been registered. Pass the generic definition, not its construction; use MakeConstructedReference on the returned member to bind owner arguments. Static generic methods are supported; instance generic methods are not.

Signatures admit primitive values, a Void result, scoped owner/method parameters, output-owned external reference-class constructions, vectors and native unions, including unions nested in generic arguments such as Task<Result<T, HttpError | JsonError>>. Union constituents are checked recursively against the same supported-signature rules; this does not admit arbitrary compositions or bypass ownership/generic-scope validation. Unsupported-signature errors include the owner, method, parameters and return type. .ctor requires an instance nongeneric Void signature. Later extensions documented below admit ref/out parameters, nested/value owners and bounded value overrides. General class virtual contracts remain unsupported. Authored interface dispatch is supported as described below. No members or access rules are resolved from the dependency: the caller asserts the semantic contract. This API does not imply that an arbitrary interface reference can be treated as a reference-class owner.

Matching authored contracts are interned. Conflicting static/result contracts with the same owner/name/arity/parameter signature reject. Null arguments throw ArgumentNullException; invalid owner/name/constructor or parameter scope throws ArgumentException; unsupported signature, conflicting contract or the shared 4,096 callable-reference limit throws InvalidDataException. Foreign output signatures reject. Existing artifact checks and writer signature/stack validation still apply.

var box = output.CreateTypeReference(dependencyIdentity, coreIdentity,
    dependencyImageSha256, "Example", "Box`1", 1);
var constructor = output.CreateMethodReference(box, ".ctor",
    new MethodSignature(PrimitiveType.Void, [SignatureType.TypeParameter(0)]));
main.LoadConstant(42);
main.NewObject(constructor.MakeConstructedReference([PrimitiveType.Int32]));

NativeGenericOwnerChecks reconstructs constructor/Get/Set/Same contracts from values, then executes construction, mutation and self-typed calls on CLR and both native containers. AuthoredFunctionReferenceChecks covers interning and invalid owner/scope/ constructor/conflicting contracts. The separate library IILGenerator remains planned.

Authored field references

AssemblyBuilder.CreateFieldReference(ImportedTypeReference declaringType, string name, SignatureType fieldType, int instanceStorageOrdinal, bool isReadOnly = false) -> ImportedFieldReference authors a public instance-field contract without a reader. The owner must be an output-owned top-level root reference-class or value-type definition with a registered native artifact digest. The caller supplies the native zero-based instance slot, including private fields in the declaration order, and must assert that this layout matches the selected artifact. The library cannot verify a supplied ordinal against bytes it has not read. CLI output uses name/type MemberRef; native output uses the ordinal. This does not change the instruction set or encode the artifact digest.

Storage supports primitive non-Void values, external reference classes (including generic constructions) and single vectors thereof. Owner type parameters are permitted within the declaring definition's arity. Construction arguments are checked recursively; method parameters, out-of-scope owner parameters, bare generic definitions and foreign output signatures reject. Static/inherited fields and byref storage are unsupported. Native value-type owners support loads from an exact value or initialized managed receiver, including generic construction; external value stores/addresses remain unsupported. Snapshot ImportReference admits native value owners as well; CLI value-field imports remain unsupported. Readonly loads work; stores reject during body validation. Matching contracts intern; conflicting names, ordinals, storage or readonly flags on the same owner reject. Null arguments throw ArgumentNullException; invalid owner, name, negative ordinal, unsupported type or foreign output signatures throw ArgumentException. Conflicts or the shared 4,096-field limit throw InvalidDataException.

var value = output.CreateFieldReference(itemReference, "Value", PrimitiveType.Int32,
    instanceStorageOrdinal: 2);
method.LoadArgument(0);
method.LoadField(value);
method.Return();

C# authored-reference checks cover body writing, interning, slot conflicts, invalid owners/ordinals and readonly-store rejection. Raven's native consumers exercise direct field load/store and alias mutation with private fields preceding public fields.

Authored interface contracts

AssemblyBuilder.CreateInterfaceReference(AssemblyIdentity dependency, AssemblyIdentity dependencyCoreLibrary, string artifactSha256, string namespace, string name) -> ImportedTypeReference authors a public nongeneric top-level interface. The overload with a final int genericArity authors an unconstrained invariant generic interface; the metadata name includes its arity suffix. The original overload remains. Identity/core/digest/name validation, errors and limits follow CreateTypeReference. Class/interface classification conflicts throw InvalidDataException, including when mixing authored references and reader imports. The caller asserts truthful declaration facts; the dependency is not loaded or inspected.

AssemblyBuilder.AddInterfaceConversion(ImportedTypeReference source, ImportedTypeReference target) -> void registers direct interface inheritance or class/value implementation. Both references belong to this output; the source is a top-level nominal definition (possibly generic), and the target is an interface identity or construction from CreateInterfaceReference. Target arguments may refer to the source's type parameters; out-of-scope arguments reject. Traversal substitutes arguments simultaneously, preserving distinct constructions and rejecting declaration cycles. Edges are idempotent and transitive conversions are derived using graph traversal. Null endpoints throw ArgumentNullException; foreign/unsupported endpoints, noninterface targets and cycles throw ArgumentException. More than 4096 distinct direct edges throws InvalidDataException. Register relationships before writing bodies that depend on them. This records conversions; it does not generate implementations in the runtime dependency.

CreateMethodReference on an authored interface now creates a nongeneric abstract instance contract requiring virtual dispatch. Static members, constructors and generic methods reject. IsInterfaceMethod and RequiresVirtualDispatch are true, and CallVirtual emits the existing dispatch instruction. Classes retain the nonvirtual contract. Native field ordinals and artifact checks are unchanged.

C# checks cover transitive class-to-interface return conversion, inherited interface calls, cyclic/invalid edges and conflicting nominal classification. Raven supplies relationships from symbols and executes its interface inheritance, alias storage and method/property dispatch samples. Generic interfaces and class inheritance remain outside this authoring slice. The library instruction-generator API is still pending.

IILGenerator

MethodBuilder.GetILGenerator() -> IILGenerator returns a stable generator for the method's authored definition. MethodDefinition.GetILGenerator() -> IILGenerator returns that same instance for an attached authored definition; detached or loaded opaque definitions throw InvalidOperationException. Body generation does not turn a loaded snapshot into an editable authored body.

The public library interface is independent of Raven's compiler emission interfaces. Raven's NeoCLR adapter translates its portable instruction stream into this library API. Builders describe declarations; the generator authors the existing definition-owned body. The generator owns append operations, locals/labels and immediate operand validation. Old public builder instruction methods forward to that generator as compatibility entry points. Write-time graph/stack validation still uses the existing writer path and internal operation representation; relocating those is separate from body authoring. There is no duplicate instruction buffer or changed encoding, opcode semantics or validation timing.

Locals: IReadOnlyList<LocalDefinition> exposes the existing slot-ordered local view. All operations below preserve the corresponding MethodBuilder contract documented in this reference and in their interface XML documentation: exact typed operand validation, method-local label/local ownership, write-time stack checking and target capability limits. Wrong opcode/operand or foreign handles throw ArgumentException; null required operands throw ArgumentNullException; write-time validation/resource failures throw InvalidDataException. Per-overload exceptions and limits remain as documented for the matching operation; the interface does not admit new opcodes or operand categories. ClearBody removes instructions and retains locals, as before. Authoring is not thread-safe. Instruction insertion/reordering and loaded-body editing are not implemented.

var entry = output.AddFunction("Main");
output.EntryPoint = entry;
IILGenerator il = entry.GetILGenerator();
il.Emit(OpCode.Ldc_I4, 40);
il.LoadConstant(2);
il.Add();
il.Return();

The complete operation signatures are listed below. These use library metadata handles, not System.Reflection.Emit or Raven interface types.

void LoadConstant(int value);
void WriteConsoleLine(string text);
void WriteConsoleLine();
void LoadArgument(int index);
void StoreArgument(int index);
void Add();
void Subtract();
void Multiply();
void Divide();
void Remainder();
void BitwiseAnd();
void BitwiseOr();
void BitwiseXor();
void ShiftLeft();
void ShiftRight();
void Call(MethodBuilder target);
void Call(ImportedMethodReference target);
void Call(NativeFunctionDefinition target);
void Return();
void ClearBody();
void LoadField(ConstructedFieldReference field);
void StoreField(ConstructedFieldReference field);
void Emit(OpCode opCode, ConstructedFieldReference operand);
void NewObject(ConstructedMethodReference constructor);
void Call(ConstructedMethodReference method);
void CallVirtual(ConstructedMethodReference method);
void Emit(OpCode opCode, ConstructedMethodReference operand);
void BindFunction(SignatureType functionType, MethodBuilder target);
void BindFunction(SignatureType functionType, ConstructedMethodReference target);
void BindFunction(SignatureType functionType, GenericMethodInstance target);
void Emit(OpCode opCode, FunctionBinding operand);
void InvokeFunction(SignatureType functionType);
void Call(GenericMethodInstance method);
void Emit(OpCode opCode, GenericMethodInstance operand);
void NewObject(ImportedMethodReference constructor);
void NewObject(ImportedConstructedMethodReference constructor);
void Call(ImportedConstructedMethodReference method);
void CallVirtual(ImportedConstructedMethodReference method);
void CallVirtual(ImportedMethodReference method);
void Emit(OpCode opCode, ImportedConstructedMethodReference operand);
void LoadField(ImportedFieldReference field);
void StoreField(ImportedFieldReference field);
void Emit(OpCode opCode, ImportedFieldReference operand);
void Call(ImportedGenericMethodReference method);
void Emit(OpCode opCode, ImportedGenericMethodReference operand);
void CallVirtual(MethodBuilder target);
void Emit(OpCode opCode, SignatureType elementType);
void CastReference(SignatureType target);
void NewArray(SignatureType elementType);
void ReserveArray(SignatureType elementType);
void LoadArrayElement(SignatureType elementType);
void StoreArrayElement(SignatureType elementType);
void LoadArrayLength();
void Emit(OpCode opCode);
void Emit(OpCode opCode, int operand);
void Emit(OpCode opCode, long operand);
void Emit(OpCode opCode, string operand);
void Fail(string message);
void Emit(OpCode opCode, MethodBuilder operand);
void Emit(OpCode opCode, ImportedMethodReference operand);
void Emit(OpCode opCode, NativeFunctionDefinition operand);
void Emit(OpCode opCode, bool operand);
void Emit(OpCode opCode, FieldBuilder operand);
void Duplicate();
void NewObject(MethodBuilder constructor);
void LoadField(FieldBuilder field);
void StoreField(FieldBuilder field);
BranchLabel DefineLabel();
void MarkLabel(BranchLabel label);
void Emit(OpCode opCode, BranchLabel label);
void LoadLocalAddress(LocalDefinition local);
void InitializeObject(SignatureType type);
void LoadDefault(SignatureType type);
LocalDefinition DeclareInt32Local();
LocalDefinition DeclareLocal(PrimitiveType type);
LocalDefinition DeclareLocal(TypeBuilder type);
LocalDefinition DeclareLocal(SignatureType type);
void LoadLocal(LocalDefinition local);
void StoreLocal(LocalDefinition local);
void Emit(OpCode opCode, LocalDefinition local);
void LoadObject(SignatureType type);
void StoreObject(SignatureType type);

GeneratorChecks verifies identity, definition access, scope/operand rejection, local preservation and CLR execution (42). NativeGenericOwnerChecks uses the interface for construction/mutation/calls and executes on CLR and both native containers. All seven Raven native consumers use the new interface through the backend adapter.

Static container validation (2026-10-02): CreateTypeReference may supply declaration identity for an authored static method reference on a static class. This does not assert that the container is an instantiable signature value. Raven keeps these admissions separate. NativeGenericMethodChecks now authors static generic references from values for both CLR and native consumers, without passing reader definitions.

Closed generic field validation (development, 2026-10-02): NativeGenericOwnerChecks authors scalar/vector fields containing an imported Box<Int32>, loads and stores them, and executes the resulting CLI assembly on .NET and native assembly on both containers. AuthoredFunctionReferenceChecks rejects open parameters, unconstructed generic definitions and foreign references. This extends storage signatures only; the field's declaring owner must still be nongeneric. No new API signature or metadata encoding is introduced.

ImportedConstructedFieldReference

ImportedFieldReference.MakeConstructedReference(params SignatureType[] typeArguments) returns an immutable constructed field with Definition, DeclaringType and substituted FieldType properties. The definition may contain owner type parameters (including vectors and nominal constructions). Arguments are copied; wrong arity, nongeneric owner, Void or foreign arguments throw ArgumentException, and null arguments throw ArgumentNullException. Substitution is simultaneous and preserves caller parameters.

IILGenerator and the forwarding MethodBuilder offer LoadField, StoreField and Emit(OpCode, ImportedConstructedFieldReference). Only Ldfld/Stfld are admitted. Null operands throw ArgumentNullException; foreign, unconstructed generic, wrong-opcode or out-of-scope operands throw ArgumentException. Writing validates receiver, storage and readonly rules and throws InvalidDataException for invalid bodies. CLI writes a MemberRef with open storage signature and a constructed parent; native writes the existing slot. These host APIs are covered by this manual reference, not the guest RavenDoc snapshot.

Generic native relationship materialization

ReadNativeAssembly now admits unconstrained invariant top-level generic interfaces and classes implementing them. TypeDefinition.Interfaces exposes immutable relationships; InterfaceImplementation.TypeArguments preserves open owner parameter ordinals or closed arguments, and InterfaceType resolves the canonical open definition. Relationships currently target interfaces declared in the same native assembly. Cyclic/invalid relationships reject during reader validation. Loaded CLI relationship materialization remains pending; no reflection facade or projection is introduced.

ImportReference(MethodDefinition, core) supports abstract generic-owner interface methods; bind owner arguments with MakeConstructedReference and emit CallVirtual. ImportReference(FieldDefinition, core) supports native generic-owner fields; bind arguments with MakeConstructedReference and emit LoadField/StoreField. Native storage and dispatch encodings are unchanged. Reader-derived and explicitly authored interface conversion paths both substitute and validate invariant arguments.

Validation: NativeGenericOwnerChecks runs reader and authored imports on .NET and executes the authored field/interface consumer with both native containers. Raven tests scope identity, both dependency orders, incompatible constructions and primitive/nominal runtime dispatch. Constraints, variance and cross-assembly relationship declarations are not added by this slice. Host APIs remain documented manually here; the guest RavenDoc assembly is unchanged.

Metadata-only Introspection facade

Namespace NeoCLR.Metadata.Experimental.Introspection, in the existing .NET metadata library. These are C# prototype types shaped after the runtime System.Introspection model, not runtime Reflection types or a complete replacement for that model.

Type Implemented public surface
MetadataLoadContext Constructor (IEnumerable<AssemblyDefinition> snapshots); IReadOnlyList<AssemblyInfo> Assemblies; Resolve(AssemblyIdentity) and Resolve(AssemblyReference) returning AssemblyInfo; Resolve(TypeReference) returning NominalTypeInfo
AssemblyInfo string Name, AssemblyIdentity Identity, IReadOnlyList<AssemblyInfo> ReferencedAssemblies, GetModules(): IReadOnlyList<ModuleInfo>, GetTypes(): IReadOnlyList<NominalTypeInfo>
ModuleInfo Logical string Name, AssemblyInfo Assembly, bool IsProjection, GetMembers(), GetTypes(), GetFunctions(); see the module reference above
TypeInfo Abstract read-only string DisplayName, bool IsNominalType; library-controlled construction
NominalTypeInfo TypeInfo plus string Name, string Namespace, string FullName, uint MetadataToken, ModuleInfo Module, nullable NominalTypeInfo DeclaringType, int GenericArity, bool IsInterface, bool IsValueType

The constructor registers at most 4096 already-read CLI/native snapshots in input order. It does not read files or expand dependencies. Null catalog/elements throw ArgumentNullException; mutable builder definitions or excessive input throw ArgumentException. Repeating the same snapshot object is idempotent; different objects with one exact identity throw InvalidDataException even when their bytes might match. No implicit image hashing, version fallback, assembly loading or code execution occurs.

Resolve(identity) requires the full identity, including version/culture/token/flags. Resolve(reference) also requires its consuming snapshot to be the registered object. Missing/conflicting scopes, missing or ambiguous types and unsupported reader scopes throw InvalidDataException. Null inputs throw ArgumentNullException. Exported forwarders, multimodule scopes and constructed TypeSpec resolution retain reader limitations. ReferencedAssemblies lazily resolves direct edges and throws when a dependency is unregistered; legal assembly cycles reuse views rather than recursively loading graphs.

Collections are read-only and views canonical within a context, including concurrent nominal lookups. Reference equality is context identity, not equality across contexts. GetTypes includes nested definitions and excludes the CLI <Module> pseudo-type. Names are display/declaration strings; Module.Assembly.Identity supplies binding scope. GenericArity describes a definition, not constructed arguments. MetadataToken is the reader's module-local token (native origin tokens included), not an execution handle.

No assembly/module token or FullName is fabricated for native inputs without that contract. The exact AssemblyIdentity is exposed instead. Additional runtime TypeInfo properties, member enumeration, constructed/array/function/parameter views and binding flags remain unimplemented. This is an explicit subset; unsupported capabilities are not represented as empty member collections. The context retains snapshots through its views and owns no disposable runtime loader; ordinary managed lifetime applies.

var context = new NeoCLR.Metadata.Experimental.Introspection.MetadataLoadContext(
    new[] { consumerSnapshot, dependencySnapshot });
var consumer = context.Resolve(consumerSnapshot.Identity);
var externalType = context.Resolve(consumerSnapshot.MainModule.TypeReferences[0]);
var declaringAssembly = externalType.Module.Assembly;

MetadataLoadContextChecks covers CLI/native navigation, exact versions, conflicts, missing dependencies, diamonds, legal cycles, foreign snapshot rejection, concurrency, context isolation and collection immutability. Raven uses this context for nominal resolution; its emission remains based on symbols. This host-only namespace is manually documented here and is not included in the guest RavenDoc reference assembly.

Constructed and field views

In NeoCLR.Metadata.Experimental.Introspection:

Type Public members added
MetadataLoadContext ResolveSignature(SignatureType signature, IReadOnlyList<TypeInfo>? typeArguments = null): TypeInfo
NominalTypeInfo GetGenericArguments(): IReadOnlyList<TypeInfo>, MakeGenericType(params TypeInfo[] arguments): ConstructedTypeInfo, GetFields(): IReadOnlyList<FieldInfo>
PrimitiveTypeInfo PrimitiveType Kind, DisplayName, IsNominalType=false
ArrayTypeInfo TypeInfo ElementType, DisplayName, IsNominalType=false
GenericParameterTypeInfo NominalTypeInfo DeclaringType, int Position, string Name, DisplayName, IsNominalType=false
ConstructedTypeInfo NominalTypeInfo Definition, IReadOnlyList<TypeInfo> TypeArguments, GetFields(): IReadOnlyList<FieldInfo>, DisplayName, IsNominalType=true
FieldInfo string Name, uint MetadataToken, TypeInfo DeclaringType, TypeInfo FieldType, bool IsStatic, bool IsReadOnly

Views are library-created and interned by context/type structure. Field collections are stable and read-only per owner view. GetFields returns all declared fields in metadata order, with no inherited lookup or visibility filtering. The token always identifies the original declaration in Definition.Module. Primitive views describe signature categories, not invented core-library declarations. Open parameter identity includes the declaring nominal definition; DisplayName (!0, etc.) is not identity.

MakeGenericType copies exactly one same-context argument per parameter. Null arguments throw ArgumentNullException; wrong arity, foreign/null/Void/bare-generic arguments, nongeneric owners and excessive nesting throw ArgumentException. Scoped caller parameters are allowed. This projects metadata, not language-level generic constraint satisfaction.

ResolveSignature accepts reader primitives, nominal references, constructions, vectors and owner parameters. Up to 32 owner arguments are copied before projection; null signature throws ArgumentNullException, foreign/null/Void/excessive arguments throw ArgumentException. Missing dependencies, unsupported signatures or absent parameter scope throw InvalidDataException. Output-builder types and method-scoped parameters are not supported. Nesting is bounded to 16. Substitution is simultaneous: supplying another owner's !0 returns that parameter unchanged rather than substituting it again.

GetFields decodes through the current reader profile and throws InvalidDataException for unavailable signatures/dependencies. Broader CLI signatures retain reader limitations. For a recursive Box<T>.Next: Box<T>, projecting Box<Int32> returns the existing constructed view without expanding its fields recursively. No runtime objects are inspected or mutated.

The names follow the runtime model; this prototype distinguishes nominal definitions from constructed views explicitly. MethodInfo/ParameterInfo, properties, full access flags, function/byref views and open method generic scopes remain follow-up work. The new host types are covered here, not added to the guest RavenDoc assembly.

Method and parameter views

Namespace NeoCLR.Metadata.Experimental.Introspection:

Type Public surface added
MetadataLoadContext Resolve(MethodDefinition): MethodInfo; ResolveSignature(SignatureType, IReadOnlyList<TypeInfo>? typeArguments, IReadOnlyList<TypeInfo>? methodArguments): TypeInfo
ModuleInfo GetFunctions(): IReadOnlyList<MethodInfo>
NominalTypeInfo / ConstructedTypeInfo GetMethods(): IReadOnlyList<MethodInfo>
MethodInfo Name, Namespace (strings), MetadataToken (uint), Module (ModuleInfo), nullable DeclaringType (TypeInfo), ReturnType (TypeInfo), GenericParameterNames (IReadOnlyList<string>), IsStatic, IsAbstract, IsVirtual (bool); GetParameters(): IReadOnlyList<ParameterInfo>; GetGenericArguments(): IReadOnlyList<TypeInfo>
ParameterInfo DeclaringMethod (MethodInfo), Position (int), ParameterType (TypeInfo)
MethodGenericParameterTypeInfo DeclaringMethod (MethodInfo), Position (int), DisplayName (!!ordinal), IsNominalType=false

Resolve requires a method definition from an exact registered snapshot. Null input throws ArgumentNullException; missing snapshots/undecodable signatures throw InvalidDataException. Methods are interned by original definition and declaring owner view. GetMethods returns all declared non-constructor methods including accessors, without inherited lookup or visibility filtering. Module.GetFunctions enumerates assembly-level functions. Enumeration collections are read-only; repeated calls preserve element identities. Constructor metadata can be resolved directly as MethodInfo; a dedicated ConstructorInfo facade is not added. Names/tokens describe declarations, never runtime handles.

Returns/parameters resolve lazily, throwing InvalidDataException for unavailable signature/dependency profiles. GetParameters preserves positions and canonical projected types. Parameter names/defaults/attributes are not fabricated when the current reader has not provided them. GenericParameterNames copies declared names. Method arguments have declaring-method identity distinct from owner parameters even at the same ordinal. Constructed owners substitute only their own arguments; method parameters remain open.

The three-argument ResolveSignature accepts explicit copied type and method scopes, each at most 32 entries. Null signature throws ArgumentNullException; null/foreign/Void arguments or excessive scope length throw ArgumentException. Missing parameter slots, dependencies or unsupported signature shapes throw InvalidDataException. Supplied arguments are substituted simultaneously without recursively rebinding caller scopes. The existing overload remains; a method parameter with no supplied method scope rejects.

Raven consumes method views for signature projection. Constraint/overload/access policy and compiler symbols remain Raven responsibilities. Method instantiation as a dedicated view, full parameter metadata, custom attributes, property views and broad CLI decoding remain pending. There is no Invoke API. Current MethodInfo/ParameterInfo names follow System.Introspection; this host prototype does not change guest APIs or commit a future identical implementation. All public host members are documented here outside RavenDoc.

Property and direct interface views (development 2026-10-03)

Namespace: NeoCLR.Metadata.Experimental.Introspection. Host C# development APIs; not guest APIs or runtime Reflection. Existing context/snapshot lifetime rules apply.

Both NominalTypeInfo and ConstructedTypeInfo expose:

Member Contract
IReadOnlyList<PropertyInfo> GetProperties() Stable read-only list of declared properties in metadata order, including non-public/static/indexed properties. No inherited lookup or visibility filter.
IReadOnlyList<TypeInfo> GetDeclaredInterfaces() Stable read-only direct interface edges in metadata order; arguments substitute in this owner's scope. Does not include transitive ancestors.

PropertyInfo is obtained from a type view; it has no public constructor:

Member Contract
string Name Metadata declaration name.
uint MetadataToken Original property token, local to the declaring module.
TypeInfo DeclaringType Open or constructed owner through which it was selected.
TypeInfo PropertyType Resolved property result/storage type after owner substitution.
IReadOnlyList<TypeInfo> IndexParameterTypes Read-only ordered index types; empty for non-indexed properties. Setter value is excluded, including setter-only properties. No parameter names/defaults/attributes are invented.
MethodInfo? GetMethod Canonical getter on the same owner, including non-public accessors; null if absent.
MethodInfo? SetMethod Canonical setter on the same owner, including non-public accessors; null if absent.
bool IsStatic Staticness recorded by the metadata accessors.
var box = context.Resolve(identity).GetTypes().Single(t => t.Name == "Box`1");
var closed = box.MakeGenericType(context.ResolveSignature(PrimitiveType.Int32));
var current = closed.GetProperties().Single(p => p.Name == "Current");
// current.PropertyType is the canonical Int32 view; its getter is also in closed.GetMethods().
var directContracts = closed.GetDeclaredInterfaces();

The C# contract fixture validates this inspection pattern. Open definitions preserve their scoped parameters; caller-provided parameters retain caller identity. Constructed relationships can be inspected edge by edge to compose substitutions, without eagerly expanding a graph. Properties and lists are cached per owner; accessor/type identity is canonical in the context. There is no invocation, property value access or runtime loading.

GetProperties() throws InvalidDataException for unsupported signatures or missing catalog dependencies. Signature scope/construction bounds from ResolveSignature still apply. GetDeclaredInterfaces() throws InvalidDataException for invalid relationships or missing dependencies and NotSupportedException when reader relationship materialization is unavailable (currently CLI snapshots). The native reader currently supports local and external interface declarations; exact dependencies are resolved through the context catalog.

Unlike .NET Reflection property access, this reports metadata only. Index types are exposed directly instead of manufacturing method-owned ParameterInfo objects for a property. Other-method semantics, full parameter metadata, transitive interface queries, constructor-specific views and generic method construction are not added here.

Inherited interface views (development 2026-10-03)

NominalTypeInfo.GetInterfaces() and ConstructedTypeInfo.GetInterfaces() return IReadOnlyList<TypeInfo> containing direct and inherited interfaces, excluding the owner. Owner arguments are substituted at each edge; diamond duplicates collapse by canonical constructed identity, so different arguments remain distinct. Results are stable, read-only and in depth-first metadata order. GetDeclaredInterfaces remains direct-only.

Invalid relationships, missing dependencies, cyclic declaration paths, more than 4,096 distinct interface views or 65,536 visited edges throw InvalidDataException. Unsupported reader relationship materialization (currently CLI snapshots) throws NotSupportedException. There is no partial success result, recursive member expansion or runtime loading. This covers the native root-class/interface profile; general class inheritance and parameter-constraint queries are not claimed. The result is cached per owner.

Generic method construction (development 2026-10-03)

Host Introspection.MethodInfo adds these members:

Member Contract
bool IsGenericMethodDefinition True for a generic declaration without supplied method arguments, even on a constructed owner.
MethodInfo GetGenericMethodDefinition() Returns this definition or the construction's definition on the same declaring owner. Throws InvalidOperationException for nongeneric methods.
MethodInfo MakeGenericMethod(params TypeInfo[] arguments) Copies same-context arguments and returns a canonical constructed view. Only callable on a generic definition.

GetGenericArguments() returns scoped parameters on a definition and copied supplied arguments on a construction. GenericParameterNames remains declaration metadata. ReturnType and GetParameters apply owner and method arguments simultaneously; each ParameterInfo.DeclaringMethod is the constructed method that exposes it. DeclaringType, Module and MetadataToken retain original provenance. No declaration mutation occurs.

var mixed = closed.GetMethods().Single(m => m.Name == "Mixed");
var call = mixed.MakeGenericMethod(context.ResolveSignature(PrimitiveType.Boolean));
// For Box<Int32>.Mixed<U>(U, T) -> T: parameters are Boolean/Int32, result Int32.

This pattern is tested by the C# fixture against equivalent CLR metadata inspection. Assembly-level functions support construction too. Supplied caller type/method parameters remain caller-scoped and are not recursively rebound. Repeated equal requests return the same view within one context; differing owners or contexts remain distinct.

MakeGenericMethod throws ArgumentNullException for a null argument array; InvalidOperationException for a nongeneric or already constructed method; ArgumentException for wrong arity, null elements, foreign-context types, Void, bare generic definitions, or argument nesting of 16 or more. Result signature projection may later throw InvalidDataException for unsupported/unavailable metadata or nesting bounds, as on open methods. Collections remain read-only. This supports the reader's unconstrained generic signature profile, not general constraint validation, runtime invocation or code emission.

Declaration facts (development 2026-10-03)

Host namespace: NeoCLR.Metadata.Experimental.Introspection.

API Contract
MetadataAccessibility CLI-shaped values: CompilerControlled (PrivateScope), Private, FamilyAndAssembly, Assembly, Family, FamilyOrAssembly, Public. Consumers apply language access rules.
NominalTypeInfo.Accessibility Declared type access, including distinct nested visibility categories on supported CLI definitions.
NominalTypeInfo.IsAbstract, IsSealed, IsStatic Metadata flags; static denotes abstract plus sealed.
MethodInfo.Accessibility, FieldInfo.Accessibility Declared member access; not filtered by caller.
MethodInfo.IsConstructor Instance .ctor classification.
MethodInfo.IsStaticConstructor Static .cctor classification.
NominalTypeInfo.GetConstructors(), ConstructedTypeInfo.GetConstructors() Read-only IReadOnlyList<MethodInfo> of declared constructors/type initializers in metadata order. Same canonical method elements as direct resolution; constructed owners substitute signatures.

GetMethods still excludes constructors. Unsupported callable signatures/dependencies throw InvalidDataException, including CLI instance signatures outside the current decoder. Enumeration does not execute initializers or load runtime types. The C# fixture checks public constructors/private fields, internal declarations, readonly/static facts and closed-owner constructor parameters. Raven supports public/internal/private native access; other categories fail explicitly rather than being treated as private.

External interface declarations

These additions extend the earlier authored relationship profile to external definitions; existing local overloads and encodings remain unchanged.

  • AssemblyBuilder.CompleteInterfaceReference(ImportedTypeReference reference) -> void asserts that all direct CreateMethodReference contracts (including accessor methods) and AddInterfaceConversion base edges have been supplied. The reference must be an output-owned open interface definition. Null throws ArgumentNullException; foreign, constructed or noninterface references throw ArgumentException. Completion is idempotent and permits explicitly empty interfaces. Adding a new method or base edge afterwards throws InvalidOperationException; reusing existing methods/edges remains valid. This is a caller assertion; it does not inspect the dependency or replace runtime linking.
  • TypeBuilder.AddBaseInterface(ImportedTypeReference contract) -> void declares an external base on an interface. AddInterfaceImplementation(ImportedTypeReference contract) declares an external implementation on a root class. Arguments can use owner generic parameters. Null throws ArgumentNullException; foreign/unregistered targets, invalid scope, duplicate edges or limits throw ArgumentException; invalid owners throw InvalidOperationException. Each external interface and inherited base must be completed before writing. Incomplete contracts and missing/mismatched implementations throw InvalidDataException. Only matching public instance methods acquire CLI implementation flags.
  • Direct definitions use new InterfaceImplementation(module.ImportReference(identity, namespace, metadataName), arguments) appended to TypeDefinition.Interfaces, after registering the matching output-owned interface contract. It shares builder validation.
  • RuntimeAssemblyContainer.WriteBinary(AssemblyBuilder assembly) -> byte[] validates and encodes the authored graph with its CLI reference projection. Null throws ArgumentNullException; invalid contracts/encoding throw InvalidDataException. No reader/importer is consulted. Native payloads remain authoritative and CLI bodies remain non-executable. Existing native-bytes container overloads cannot reconstruct external interface method contracts and throw NotSupportedException for these declarations; use the graph overload. This restriction also applies to NativeAssemblyDefinition.CreateReferenceAssembly without resolved external contracts.

Reader snapshots preserve exact scoped interface identities and constructed arguments; GetDeclaredInterfaces/GetInterfaces resolve them through the explicit metadata context. Missing or wrongly classified dependencies reject during resolution. Generic diamonds retain canonical views and deduplicate the common construction.

var value = output.CreateInterfaceReference(dependency, core, digest, "Example", "Value`1", 1);
output.CreateMethodReference(value, "Get", new(SignatureType.TypeParameter(0), []));
output.CompleteInterfaceReference(value);
var box = output.AddClass("Example", "Box");
box.AddInterfaceImplementation(value.MakeGenericInstance(PrimitiveType.Int32));
var get = box.AddInstanceMethod("Get", new(PrimitiveType.Int32, []));
get.GetILGenerator().LoadConstant(42);
get.GetILGenerator().Return();
var image = RuntimeAssemblyContainer.WriteBinary(output);

ExternalInterfaceChecks validates definition/builder parity, CLI flags and execution, PE/native round trips, external generic diamond resolution and native linked dispatch. No format version change is required. The C# development API remains documented here rather than through guest RavenDoc.

Native Self signatures

Model.SignatureType.Self is an immutable singleton signature node; bool IsSelf identifies it. It is neither a primitive nor a positional type/method parameter. ToString() returns Self. It consumes no generic arity. Attaching it to a bodyless instance interface method (directly or through AddInterfaceMethod) or its associated property supplies its scope. Vectors and unconstrained nominal constructions can contain Self. Class signatures must use the actual nominal declaring type instead.

Native writing preserves the existing SelfType encoding; the binary payload and format versions do not change. Native readers reject unresolved Self in fields, locals, free functions and class method signatures with InvalidDataException. Builder attachment rejects those declarations with ArgumentException. Standalone constructions may retain Self, like an open parameter, but their eventual use must provide the interface scope.

Introspection.SelfTypeInfo : TypeInfo exposes:

  • TypeInfo DeclaringType: canonical open or constructed interface view supplying scope.
  • string DisplayName: the interface display label followed by .Self, not an identity.
  • bool IsNominalType: always false.

Method results/parameters and property types project to the same context-canonical Self view for the same owner. Constructing I<T> substitutes T while retaining a distinct Self scope for I<int>. No generic ordinal or runtime handle is exposed. Calling public MetadataLoadContext.ResolveSignature(SignatureType.Self) without a member scope rejects with InvalidDataException; use the declared member views. Contexts do not share identity.

Executable CLI AssemblyBuilder.Write() rejects Self with InvalidDataException. The reference-only CLI projection in PE/#Neo uses the existing value-type marker System.Runtime.CompilerServices.Self, scoped to the explicitly supplied core identity. It is only a transport representation; it has no CLR implementing-type semantics. Native materialization reads the authoritative payload, never the marker. Both container variants and immutable snapshot writing preserve the native signature.

This slice supports contract declarations and inspection. Implementation substitution, typed callself authoring, static Self interface methods, Self-containing inheritance, Raven native symbol projection/emission and general byref/function introspection remain subsequent work. Existing runtime Self execution does not imply these host APIs are ready. Tests: SelfSignatureChecks (C#), with a generated PE/#Neo loaded and verified by NeoCLR; its entry point returns 42 independently of Self dispatch.

Parameter passing modes

Introspection.ParameterInfo.PassingMode : ParameterPassingMode preserves the declared calling convention. ParameterPassingMode.Value means a copied value, Ref means a writable reference initialized by the caller, and Out means a writable reference assigned by the callee before normal return. ParameterType exposes the value/element type, not a byref wrapper. Position and canonical DeclaringMethod remain unchanged. There are no runtime objects, argument addresses or invocation operations in these views.

Native method materialization retains existing ByRef nodes and out_parameters indices in MethodSignature. Parameter views substitute owner/method arguments within the referenced element, including vectors. Copying a snapshot preserves the same modes. Neither native format 5 nor the binary container schema changes. Unsupported readonly In metadata is rejected by signature recognition and introspection instead of fabricated as writable ref; byref constructors, byref returns and general readonly signatures remain unsupported. Existing supported CLI static signatures expose the same ref/out distinction.

AssemblyBuilder.CreateMethodReference accepts writable ref/out parameter signatures on supported class/interface methods. Its MethodSignature carries ByReference(element) and zero-based outParameters; conflicting ref/out contracts reject with InvalidDataException. Constructed external interface traversal substitutes elements and retains output indices. Constructor byrefs still reject. Namespace-function symbol-authored references retain their previous bounded signature profile. No dependency definitions are reopened to discover modes.

Validation: C# ParameterModeChecks covers manual/builder declarations, both native containers, open/constructed scopes, CLI mode parity, readonly rejection and conflicting contracts. The Raven three-assembly driver case executes inherited generic ref/out dispatch on both targets with library sources removed; incompatible implementations publish nothing.

Union payload foundation

The metadata producer now accepts direct nominal and constructed fields in owned value types, including a Payload<T> embedded in a Carrier<T>. Builder calls and manually attached field definitions share validation. Writing rejects recursive inline storage and limits owned layout traversal to depth 64 and 4096 visited constructions; references and vectors terminate inline traversal. Native input validates the same owned layouts. External dependency layouts still require explicit dependency resolution and runtime linking; this check does not load dependencies implicitly.

AssemblyDefinition.ReadNativeAssembly now materializes unconstrained top-level value declarations, signatures, fields and supported constructors/methods. IsValueType reflects the native category; sealed/sequential flags are preserved without inventing a CLI System.ValueType dependency. ImportReference overloads retain the explicit matching output core requirement. Nested declarations, constrained owners and generic instance methods remain outside this native snapshot profile. Native snapshots remain immutable and preserve their original bytes on Write.

This matches CLR inline value storage and copy semantics: an executable tag/payload fixture returns 42 on both runtimes after mutating an independent copy. Direct native imports of nongeneric/generic value constructors and methods also execute on both. The fixture uses an Int32 tag and is a metadata contract test, not a replacement for Raven union lowering or proof that source Optional compiles.

Raven maps the introspection value category to Struct and its semantic ValueType base; generic field substitution remains in introspection. It does not reopen imported metadata in emission. Source value declarations, nested union cases, the Byte tag, synthesized members and symbol-authored external value operands remain the next compiler work. Runtime-library union sources are unchanged. No format version change, CLI projection fallback, runtime implementation change or performance claim is needed.

Native nested case metadata

AssemblyDefinition.ReadNativeAssembly retains supported nested class/value ownership beneath nongeneric declaring types, including generic nested value cases. Local signature lookup keys include the declaring token; external TypeRef rows use nested TypeRef scopes. Same-named cases beneath different companions remain distinct. Nested public/internal accessibility, canonical declaring views and constructor/member signatures survive direct native reading without a CLI projection. ImportReference accepts these scoped native definitions with the existing explicit matching core policy.

Raven publishes nested symbols as members of their declaring type, preserving their namespace and containing-type identities; namespace member and simple-name lookup do not flatten them. Generic nested field substitution stays in introspection. Emission continues to reject native nested operands outside its symbol-authored capability profile.

This follows CLI NestedClass/TypeRef identity semantics using existing native relationship encoding; no schema change or implicit dependency loading is required. C# checks cover same-named local/external payloads, multiple nesting levels, internal visibility, missing dependencies and cyclic owners. Direct native nested generic/nongeneric constructor imports execute on CLR and NeoCLR (42). Native semantic probes retain owner/field identity.

This is a reader/importer prerequisite for union cases, not source union completion. Nested types that capture generic enclosing parameters remain unsupported. Source union declaration collection, nested definition emission, Byte discriminators and complete synthesized union contracts remain pending. Existing immutable snapshot behavior is unchanged.

Byte signatures and IL generation

PrimitiveType.Byte denotes unsigned 8-bit storage, encoded as CLI ELEMENT_TYPE_U1 and native Byte. It is available in primitive method signatures, fields, locals, array elements and imported signatures. Readers and introspection retain the Byte identity. As in CLI, loading Byte produces an Int32 evaluation-stack value; storing into Byte truncates to eight bits, and loading zero-extends. ref Byte remains distinct from ref Int32; stack normalization does not erase storage or managed-pointer identity.

method.GetILGenerator().Emit(OpCode.Conv_U1) consumes an Int32 or Int64 and produces an Int32 containing the low unsigned eight bits. It encodes CLI/native conv.u1 and performs unchecked truncation, including -1 → 255 and 298 → 42. Other input categories reject during body validation; floating-point conversion is outside this writer profile. The legacy MethodBuilder.Emit forwarding API accepts the same opcode, but new code should use IILGenerator. No new native format version or runtime operation is required.

This matches CLI small-integer storage/evaluation behavior; the explicit Byte signature costs another supported primitive category but avoids widening union tags in metadata. C# coverage checks CLI/native round trips, field/method imports, local/array/field storage, conversion boundaries, CLR execution and incompatible by-reference rejection. The native artifact executes using the runtime's existing Byte storage and conversion implementation.

Value interfaces and constrained calls

TypeBuilder.AddInterfaceImplementation(TypeBuilder|GenericTypeInstance|ImportedTypeReference) and TypeDefinition.Interfaces.Add admit value-type owners as well as root classes. Owned, constructed and registered external relationships retain their existing ownership, completeness, signature and duplicate validation. The native reader retains these edges; CLI emission writes ordinary InterfaceImpl rows and implementation method flags. Declaring a relationship does not introduce implicit boxing in the body API.

New IILGenerator members:

void CallConstrained(TypeBuilder receiverType, MethodBuilder target);
void Emit(OpCode opCode, TypeBuilder receiverType, MethodBuilder target);

The call profile requires an owned nongeneric implementing type and an owned nongeneric interface contract. Instance calls require a value-type implementation; static calls admit class or value-type implementations and consume no receiver. The raw overload accepts OpCode.Callvirt for instance contracts and OpCode.Call for static contracts. Null operands throw ArgumentNullException; foreign, generic, nonconforming, nonvalue instance receivers or invalid targets/opcodes throw ArgumentException before appending. The existing instruction bound applies. Writing validates complete implementations, parameters and the exact managed receiver address; invalid bodies throw InvalidDataException. Arguments follow the receiver on the stack.

var il = method.GetILGenerator();
il.LoadLocalAddress(counter);
il.CallConstrained(counterType, nextInterfaceMethod);
// Equivalent atomic typed emission:
// il.Emit(OpCode.Callvirt, counterType, nextInterfaceMethod);

For instance contracts, CLI encoding is constrained. plus callvirt; native encoding uses the existing borrowed callself instruction. Both dispatch using the addressed storage, so mutations affect that instance and leave prior copies independent. This implements the value-implementation branch of .NET constrained dispatch. Reference receivers, external/constructed call targets, open generic receivers, and boxing fallbacks remain outside this initial authoring profile. The bounded API costs a separate validated operand form but prevents an incomplete prefix from being left in a body. No native format version or runtime code change is required. This operation is exposed on the metadata IL generator, not added to method builders or Raven's shared IL interface.

Value override authoring

MethodBuilder TypeBuilder.AddOverride(string name, MethodSignature signature);

The initial profile accepts public instance ToString() -> String on a value type, including a generic value owner. The method itself cannot be generic. The result is an attached definition with a managed receiver; use GetILGenerator() for its body. Null signatures throw ArgumentNullException. Unsupported names/signatures, duplicate methods and method limits throw ArgumentException. Class, interface and static owners throw InvalidOperationException before attachment.

Manual authoring uses the same path: construct MethodDefinition with CLI Public | Virtual (0x46), append it to TypeDefinition.Methods, then obtain its builder with MethodBuilder.ForDefinition. HideBySig is added by the writer. Do not specify Abstract or NewSlot. Interface implementation inference preserves this override rather than changing it into a new virtual slot. Existing nonvirtual AddInstanceMethod behavior is unchanged.

var display = valueType.AddOverride("ToString", new(PrimitiveType.String, []));
var il = display.GetILGenerator();
il.Emit(OpCode.Ldstr, "Example value");
il.Return();
var cliImage = assembly.Write();

This follows .NET CLI Virtual/ReuseSlot semantics. C# execution verifies boxed Object.ToString dispatch, generic value construction, interface dispatch to the same implementation, definition/builder parity and PE flags. The restricted profile avoids inventing general inheritance resolution; its cost is that other Object slots and class overrides remain unsupported.

Native binding: before native writing, register exactly one explicit System library with BindNativeLibrary(referenceSnapshot, nativeLibrary, coreIdentity). The existing retained CLI bootstrap snapshot must declare public virtual Object.ToString() -> String; the native library must be module System and provide the matching public virtual instance slot, with no generic parameters, byref receiver, output modes or no-result semantics. Missing, ambiguous or incompatible bindings throw InvalidDataException. No library is loaded implicitly. This remains an explicit bootstrap bridge, not an application-reference fallback or a general Object/Reflection API.

Native writing includes the registered assembly identity and native module/revision binding even without a call to the dependency in the body. Override names use the runtime's owner.ToString slot convention, with is_virtual/is_override and receiver_byref. Ordinary method naming and interface encodings are unchanged. These are existing format-5/runtime fields; no format bump or runtime change is required.

Native readers retain the CLI Virtual/ReuseSlot flags, validate the bounded shape and System binding, and native imports preserve the call name. Both native semantic snapshots and reference-only CLI projections retain the declaration meaning. Execution additionally checks the linked dependency's actual definitions. Reader validation is not proof that runtime bodies or external artifacts have been verified.

The C# --native-value-override integration mode writes a native library, rereads it, emits a separate direct-call consumer and executes it. A neoIL harness calls an API-produced generic boxing method with ordinary and generic values, then calls Object.ToString; it also checks reference identity and primitive display, returning 42 using the real retained System bundle. This does not claim Raven union execution. Raven now consumes the bounded override with explicit runtime-seed binding. Generated display conversions/formatting operations and union/case metadata preservation remain pending.

Typed boxing

AssemblyBuilder.CoreObjectType : ImportedTypeReference returns an interned, output-owned System.Object reference in the explicitly supplied CoreLibrary. It performs no loading or dependency discovery. A signed core identity is supported for this exact reference; other imported signed nominal identities remain outside the bounded profile.

IILGenerator.Box(SignatureType type) and Emit(OpCode.Box, SignatureType type) consume the exact storage signature and push CoreObjectType. Types may include primitives, owned/imported nominal types, vectors and in-scope owner/method generic parameters. Void, managed references, Self, Function, foreign owners and out-of-scope parameters reject. Operand errors throw ArgumentException (null throws ArgumentNullException); stack errors and missing native bindings throw InvalidDataException before an image is returned. The new operation belongs to the IL generator, not the method builder.

CLI encoding is standard box (0x8c) with a TypeDef/TypeRef/TypeSpec operand. Native encoding uses the existing box instruction and nominal System.Object result. Value storage is copied; reference instantiations preserve object identity, including null on CLR. Native String uses the runtime's object representation. Native writing requires a BindNativeLibrary mapping for the exact core identity, module System, and a matching public System.Object class. No runtime format change, automatic dependency load or application reference projection is introduced. C# tests execute method/owner generic scopes on CLR; the native integration harness exercises generic value boxing, primitive display and reference identity against the retained System seed.

var t = SignatureType.MethodParameter(0);
var method = assembly.AddFunction("Box", new(assembly.CoreObjectType, [t], ["T"]));
var il = method.GetILGenerator();
il.LoadArgument(0);
il.Box(t);
il.Return();

Owned field addresses

IILGenerator.LoadFieldAddress(FieldBuilder field) and LoadFieldAddress(ConstructedFieldReference field) consume an initialized receiver and push a managed reference to its actual field storage. The equivalent raw operations are Emit(OpCode.Ldflda, field) on these two operand categories. Existing forwarding Emit methods on MethodBuilder retain parity; no new builder-body convenience API is added.

The field must belong to this output, be an instance field and be mutable. Constructed references substitute the exact owner arguments; open definition operands require the matching owner scope. A reference-class receiver is consumed directly. A value receiver must already be addressed; a temporary value on the stack is rejected instead of silently mutating a copy. Uninitialized locals/out parameters/constructor fields reject on write. Readonly and imported field addresses remain explicitly unsupported in this profile.

Null arguments throw ArgumentNullException; foreign/readonly/out-of-scope operands throw ArgumentException without appending instructions. Instruction limits and incorrect stack or initialization contracts throw InvalidDataException before producing output. Reads, stores and calls through the resulting managed reference reuse their existing exact-type checks. CLI uses standard ldflda (0x7c) with a FieldDef/MemberRef; native uses the existing ldflda layout ordinal. No format or runtime behavior change is required.

C# tests execute nested field mutation through a constructed generic holder and verify that its object alias sees 42 on CLR and NeoCLR. They also reject readonly and foreign operands, temporary value receivers and uninitialized local receivers.

Reference tests

IILGenerator.IsNull() / Emit(OpCode.ReferenceIsNull) consume an ordinary nominal, interface, vector or String reference and push Boolean. They perform a null identity test, not a user-defined equality operation. CLI uses ldnull/ceq and accounts for its temporary stack slot; native uses ref.isnull. Managed references and unboxed values reject on write.

IsInstance(SignatureType target) / Emit(OpCode.Isinst, target) implement standard isinst: a matching reference or null, with no unboxing or exception on type mismatch. Reference targets retain their signature (including String). Value and scoped generic targets produce CoreObjectType, representing a box or null. Void, Self, Function, managed references, foreign owners and out-of-scope parameters reject before instruction append. A native value/generic type test requires the same explicit System core binding as boxing. No target or dependency is inferred from the executing host.

CastReference / Emit(Castclass, target) additionally accept String targets and String inputs. Failed checked casts retain runtime InvalidCast behavior; null remains null. ArgumentNullException/ArgumentException describe null or invalid operands; stack, limit and native-binding failures throw InvalidDataException before an image is returned. These operations add no metadata format or runtime behavior. C# tests exercise null and matching/nonmatching primitive/reference type tests, generic scopes and String identity on CLR; native binary tests verify/run 42 with the explicit retained-System bootstrap.

Core display dispatch continuation (2026-10-03): imported public instance System.Object.ToString() -> String from the exact explicit CLI core snapshot now supports CallVirtual. Native output requires the validated System slot binding; missing, ambiguous, nongeneric/signature-mismatched or nonvirtual slots reject. This reuses CLI callvirt and native virtual dispatch without a format/runtime change. Raven opts into a bounded semantic Object display capability; other virtual class calls remain unsupported. Runtime Contract and importer/emitter boundaries are unchanged. API-authored boxed value overrides execute through Object; ordinary Raven commands print 42 and text on both targets. The union preflight now reaches a synthesized get_Value null literal. Full native union/case metadata and execution remain pending.

Type custom attributes

Host-only namespace NeoCLR.Metadata.Experimental.Model:

  • CustomAttributeArgument(SignatureType type, object? value) stores immutable Type and Value. Supported fixed arguments are String (including null), Int32, Boolean and nominal Int32-backed enums; see the development extension below. Other type/value combinations throw ArgumentException. Strings are strict UTF-8 and bounded to 65,536 UTF-16 code units.
  • CustomAttributeDefinition(TypeReference attributeType, IEnumerable<CustomAttributeArgument> arguments) authors an instance .ctor reference without implicitly loading dependencies. Overloads taking MethodDefinition constructor or ImportedMethodReference constructor additionally validate the fixed arguments against the constructor signature. Owned constructors must be public; references must belong to the output module.
  • AttributeType exposes the nominal owner; GetConstructorSignature() and GetValue() return owned copies of the CLI constructor signature and custom-attribute blob. GetArguments() returns read-only decoded fixed arguments. Inspection never runs a constructor. Unsupported argument/signature categories throw NotSupportedException; malformed supported data throws InvalidDataException.
  • TypeDefinition.CustomAttributes : IList<CustomAttributeDefinition> is append-only on authored, attached definitions and read-only on loaded snapshots. The corresponding TypeBuilder.AddCustomAttribute(CustomAttributeDefinition attribute) uses the same ownership/limit validation. Foreign references throw ArgumentException; missing local constructors or exceeded graph limits reject on write. At most 256 attributes per type and 256 fixed arguments per attribute are supported.

Host-only namespace NeoCLR.Metadata.Experimental.Introspection:

  • NominalTypeInfo.GetCustomAttributes() : IReadOnlyList<CustomAttributeInfo> returns cached metadata-only views in declaration order.
  • CustomAttributeInfo.Namespace and Name inspect the stored owner identity; GetArguments() decodes data without resolving dependencies.
  • CustomAttributeInfo.GetAttributeType() : NominalTypeInfo resolves the canonical owner through the explicit MetadataLoadContext catalog. Missing or mismatched dependencies throw InvalidDataException. No runtime reflection or constructor execution is involved.

Authoring uses top-level nongeneric nominal attribute owners. See the later member and payload extensions for current development scope. Array and System.Type arguments remain unsupported. Loaded CLI blobs remain available as raw copies even when typed decoding is unsupported. This does not add mutable loaded-assembly rewriting.

CLI output uses the existing CustomAttribute table, constructor MemberRef and standard prolog/fixed-argument/named-count blob. Native PE/#Neo output uses the runtime's existing custom_attributes records; its CLI projection contains equivalent standard blobs. This is an interim dual representation, not a CLI-authoritative runtime format or a new union wire category. Native constructor-bearing records currently do not enforce CLI System.Attribute inheritance; the .NET execution control uses System.ObsoleteAttribute. C# tests cover actual CLR decoding, native round trips, explicit dependency resolution, malformed records and runtime verification/execution without invoking an attribute ctor.

Intrinsic bootstrap mappings

AssemblyBuilder.BindNativeLibrary now permits static methods on the exact explicitly bound core System.String owner when the native module is System. Selected methods still require matching public signatures, results and owner identity. Native calls encode their owner as primitive String, while CLI output retains its TypeRef/MemberRef identity. This does not admit String as an ordinary nominal imported class or add instance members. An imported value System.Char from that same core binding encodes native type operands as Char, including generated formatting type tests; it is not a new public Char primitive signature API. Missing/wrong bindings fail before returning an image.

These are existing runtime primitive representations, not new union semantics or wire categories. An executable C# fixture checks concatenation, a nonmatching boxed Int32/Char test, rejected owner/result/module changes and continued rejection of nominal String import. Method-body validation failures include the declaring method for actionable diagnostics.

Parameter names and authored value references

MethodDefinition.ParameterNames : IReadOnlyDictionary<int, string> exposes sparse, zero-based declared names. MethodDefinition.SetParameterName(int position, string? name) and the forwarding MethodBuilder.SetParameterName set a name or clear it with null. The position must be inside the signature; names must contain 1–1024 characters and no control characters. Loaded snapshots reject mutation. Names are descriptive and do not change method identity or parameter modes.

CLI output uses ordinary Param names; native output uses the existing aligned parameter_names array. Readers reject names outside the signature and malformed native array lengths. Introspection.ParameterInfo.Name : string? returns null for an unnamed parameter and retains names through constructed generic views.

AssemblyBuilder.CreateValueTypeReference(AssemblyIdentity dependency, AssemblyIdentity dependencyCoreLibrary, string artifactSha256, string namespace, string name, int genericArity = 0) authors a public value identity. Register any supported generic category requirements with SetSpecialConstraints. It has the exact identity, core, digest and resource validation of CreateTypeReference. It neither loads the dependency nor proves its storage layout.

AssemblyBuilder.CreateNestedTypeReference(ImportedTypeReference declaringType, string name, int genericArity = 0, bool isValueType = false) authors a public nested identity. The declaring reference must belong to this output and carry a native artifact contract; generic/constructed declaring scopes are unsupported. The nested namespace is empty and its arity is its own. Foreign scopes throw ArgumentException; unsupported identities or scope categories reject through normal import validation.

CreateMethodReference now also accepts these value and nested owners and their supported nominal signature operands. Instance value calls retain managed receivers; physical nesting survives encoding. The caller supplies semantic facts and an explicit artifact digest. This does not introduce dependency loading, virtual override authoring, byref constructors or generic instance methods.

C# contracts exercise CLI/native name round trips, constructed parameter views, readonly snapshots, invalid names/positions/array lengths, and symbol-authored nested generic value constructors executed by the CLR. The native Raven union consumer additionally executes these references on neoCLR. No metadata version change is required.

Development validation, 2026-10-03: authored value-interface edges retain the relationships needed by imported source Optional/Result carriers. Unboxed value-to-interface assignment remains rejected; boxing or constrained dispatch is still required. C# tests cover idempotent value edges, wrong target kinds and foreign ownership. The unchanged source-library consumer executes separately on neoCLR with the bounded union bootstrap.

Function signature views

Introspection.FunctionTypeInfo : TypeInfo is a context-owned metadata facade for an existing native callback shape. It exposes no callable instance, invocation or reflection.

Member Contract
TypeInfo ReturnType Canonical result view; primitive Void for an explicit no-result signature.
IReadOnlyList<TypeInfo> ParameterTypes Immutable ordered value parameter views. Names and callable targets are not signature identity.
bool NoResult True only when invocation leaves no result; an inhabited unit type is distinct.
bool IsNominalType Always false.
string DisplayName Diagnostic signature text, not a serialized identity or resolver key.

MetadataLoadContext.ResolveSignature and member views now project function shapes, recursively substituting owner and method parameters and resolving nominal dependencies. Equivalent shapes share a view in one context; contexts never share identity. Missing catalog dependencies and unscoped parameters throw InvalidDataException. Existing foreign argument and nesting limits remain enforced. There are at most sixteen value parameters; byref callback parameters and generic callback declarations remain unsupported. Outer method/type parameters can appear inside a callback.

AssemblyDefinition.ReadNativeAssembly preserves these shapes in supported method, field and property signatures, using the existing function encoding without a format version change. AssemblyBuilder.CreateMethodReference also accepts bounded callback operands authored from semantic facts; dependency resolution is not added to emission. The earlier test rejecting all callback fields now checks their retained signature.

C# tests cover open and constructed owner/method substitution, canonical views, external identity, missing dependencies, explicit no-result signatures and context isolation. Raven currently imports value-returning callbacks through its existing callable symbols and explicit primitive bootstrap. Explicit no-result callback import still rejects rather than being silently changed to an inhabited-unit result. This completes ArrayList's Boolean predicate case; it does not integrate the separate structural Function language experiments.

Exact unboxing and generic conversions

IILGenerator.UnboxAny(SignatureType target) and IILGenerator.Emit(OpCode.UnboxAny, SignatureType target) consume an object reference and push the requested storage type. MethodBuilder's existing raw Emit forwarding overload accepts the same opcode; the convenience operation lives on the IL generator. The target may be a primitive value, nominal value/reference, vector, or caller-scoped method/type parameter. Void, managed references, Self and function signatures reject with ArgumentException, as do foreign owners and unbound generic parameters. Stack validation on write rejects non-reference input with InvalidDataException.

CLI output uses unbox.any (0xA5); native output uses the existing unbox.any operation. Value targets require an exact boxed type and reject null or a different box at execution. Reference targets preserve object identity and admit null under the runtime's existing checked-reference rules. This is not a numeric conversion and creates no new native format or semantic category. Unlike CastReference, a generic target may instantiate as either a value or reference type.

var il = method.GetILGenerator();
il.LoadArgument(0); // object parameter
il.UnboxAny(SignatureType.MethodParameter(0));
il.Return();

Validation includes CLR execution for primitive/method/owner generic scopes, reference identity/null, incorrect boxes and invalid authoring/stack inputs. The unchanged native query library separately imports and executes OfType over heterogeneous boxed values and reference payloads; see the bootstrap query acceptance workflow.

AssemblyBuilder.SetArrayBacking(TypeBuilder type)

Development API: selects the output-owned nominal class backing native vectors. type must be a nonabstract, nonstatic, nonnested generic class with one unconstrained parameter and exactly one private field of type T[]. Its local base may be absent or the output-owned native Object root (development, 2026-10-07). Reading preserves that relationship; runtime linking requires the exact host-selected, fieldless root. Other bases remain unsupported. Repeating the same selection is idempotent; a different selection throws InvalidOperationException. Null throws ArgumentNullException; foreign/incompatible descriptors throw ArgumentException. Native writing revalidates the selection after subsequent definition edits.

This host execution policy is encoded beside ordinary definitions in the native assembly manifest; it does not alter CLI array signatures or make CLI arrays implement custom interfaces. The runtime requires exactly one selected descriptor across linked assemblies. Its storage field aliases vector identity; replacing/addressing that field and allocating the descriptor as a nominal object are unsupported. Older readers reject this optional format-5 field. NativeAssemblyDefinition.ReadAssembly validates its identity and storage shape and retains it in the immutable native snapshot. See the integration documentation for source Array<T>, iteration configuration and executable validation.

Imported value overrides and slot facts

Introspection.MethodInfo.IsNewSlot exposes the CLI NewSlot declaration bit, including on constructed views. A virtual method with this bit clear reuses an inherited slot; this is metadata information, not a language-level override-resolution service.

AssemblyBuilder.CreateMethodReference(ImportedTypeReference declaringType, string name, MethodSignature signature, bool isStatic = false, bool isOverride = false) additionally accepts the bounded value override contract: an instance, nongeneric ToString(): String on a value owner (including a generic value definition). Other override shapes throw ArgumentException. Conflicting reuse-slot/ordinary references throw InvalidDataException. Repeated equivalent references intern normally. The reference retains a managed receiver and native override identity; it does not request class/interface virtual dispatch. No dependency metadata is reopened by this authoring API. CLI MemberRef signatures remain unchanged. Wider overrides remain unsupported.

The optional isOverride parameter preserves source calls but changes the experimental host method signature; rebuild binary consumers with the matching metadata library.

.NET acceptance service adapters (development tooling only)

The separate NeoCLR.DotNetServices test assembly under the bootstrap tooling exposes:

  • System.Runtime.CompilerServices.CheckedStorage.Reserve<T>(int length) -> T[]: allocates a real CLR array. Negative lengths and allocation failures propagate CLR exceptions. Slots have CLR default initialization; native tracked-uninitialized storage is not emulated.
  • System.Runtime.CompilerServices.RuntimeFailure.Terminate(string message) -> void: writes the message to stderr and exits the process with status 1. Marked DoesNotReturn.

These executable host adapters contain no reader/writer APIs or source library types and are not selected for guest RavenDoc publication. They support the paired .NET assessment, which currently fails later on unit storage mapping.

The development .NET acceptance service additionally exposes the public readonly empty System.Runtime.CompilerServices.UnitValue struct. It is the inhabited unit storage type selected by the explicit .NET bootstrap manifest; default initialization is its sole value. It is not CLR System.Void and adds no metadata reader/writer or guest runtime API. The host compiler contract and ordinary CLI signatures carry this mapping without a native format extension. See the integration documentation for the remaining array-adapter limitation.

Declared generic type-parameter names

GenericParameterTypeInfo.Name: string returns the declared name from a supported native snapshot, for example TItem. It has no parameters and does not resolve dependencies or load runtime types. Identity remains the owning declaration plus Position; DisplayName remains !ordinal. Equal names on different owners do not merge parameters. CLI snapshots currently do not materialize these names: accessing Name throws NotSupportedException, rather than inventing a name. No generic constraints or variance facts are added here.

var parameter = (GenericParameterTypeInfo)nativeType.GetGenericArguments()[0];
string declaredName = parameter.Name;

This host-only member is outside the guest RavenDoc selection and is documented here. C# contracts cover native name/ordinal/canonical identity and explicit CLI rejection.

Primitive comparer bootstrap imports

AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) additionally supports explicit CLI core String/Int32/Int64 members bound to an executable native System seed. It validates snapshot/core identity, primitive owner, public concrete nonvirtual method, parameters/results and receiver passing mode. String instance calls consume a String value; Int32/Int64 instance calls consume a managed address of their exact width. Generic owner or nominal layout inference is not introduced. String still cannot be imported as an ordinary nominal class through this bootstrap mapping. ImportedMethodReference keeps its original CLI owner identity and reports RequiresManagedReceiver for Int32 and Int64. IILGenerator.Call/Emit validate the actual primitive receiver and preserve the ordinary CLI member reference encoding; native output uses the existing primitive owner encoding.

The exact public virtual core System.Object.GetHashCode() -> Int32 slot is now admitted by ImportReference and IILGenerator.CallVirtual/Emit(Callvirt, ...). Native output requires an explicit System binding with matching virtual/result/receiver flags. Missing, wrong or nonvirtual slots throw InvalidDataException before an image is returned. This does not enable arbitrary class virtual imports. No public signature, metadata version or runtime instruction changes are required.

C# native comparer binding checks execute String.Equals, Int32/Int64.CompareTo and Object hash calls and reject wrong receiver modes, virtual primitive methods, wrong hash result and unbound native hash dispatch. Int64 checks also reject wrong primitive owner, missing method identity and wrong result width, and execute both signed extrema and equality. The source-built StringComparer consumer tests existing UTF-8 scalar ordering and Unicode simple folding; .NET ordinal UTF-16 ordering is not substituted. This host API is documented manually; the separate guest RavenDoc snapshot check remains stale and was not regenerated for this host-only change.

Argument addresses and CLI Object signatures

IILGenerator.LoadArgumentAddress(int index) and Emit(OpCode.Ldarga, int index) load a managed address to an ordinary by-value argument. Indexing includes the implicit instance receiver: static parameter zero uses index 0; an instance method's first parameter uses index 1. Changes through the address affect that invocation's parameter storage, preserving normal call-by-value isolation from the caller. Use Ldarg for an already managed-reference parameter. Receiver slots, byref parameter slots and negative or out-of-range indices reject with InvalidDataException during writing, even when the instruction is unreachable. Indirect operations and calls require the exact addressed type. Instruction-limit failures retain existing emission-time validation. Raw forwarding MethodBuilder.Emit also accepts Ldarga; new code should use GetILGenerator().

Both writers share validation: CLI writes the standard ldarga instruction (FE 0A and a 16-bit argument index); native writes the runtime's existing ldarga operation. No runtime or format-version change is needed. C# tests execute mutation through static and instance parameter addresses on CLR and NeoCLR, and reject invalid slots and mismatched stores.

Imported CLI ELEMENT_TYPE_OBJECT signatures (including vector elements) now map to the consumer's explicit CoreObjectType after compatible core validation. Primitive-only signature recognizers retain their narrower contract; original signature bytes remain unchanged. The native comparer binding test imports and executes Object.ReferenceEquals. This does not add implicit dependency loading or nominal layout inference.

These host C# APIs remain covered by this manual reference, separate from guest RavenDoc selection. The known stale guest documentation snapshot is not regenerated by this slice.

Explicit core character signatures

AssemblyBuilder.ImportReference(MethodDefinition, AssemblyIdentity) decodes CLI ELEMENT_TYPE_CHAR (0x03), including vector elements, as an output-owned value reference to System.Char in the supplied core identity. The CLI writer emits canonical 0x03 for that exact top-level, nongeneric core value type. Other nominal types are unchanged; the signed-core exception is limited to the existing Object and this Char identity. CLI execution retains UTF-16 code units, including surrogate values.

With an explicit native System binding, that core Char reference uses the existing native grapheme Char storage. Imported Char methods must be public, concrete and nonvirtual with a managed receiver matching the seed. String.get_Item can return Char; Char.ToString preserves the grapheme text. Calls encode the intrinsic Char owner instead of Named(System.Char). This is a target representation difference, not reinterpretation of .NET characters as graphemes during CLR execution.

AssemblyDefinition.ReadNativeAssembly materializes Char signatures using the exact native type alias. Missing aliases, wrong namespace/category or nested character aliases reject with InvalidDataException. NativeAssemblyDefinition.CreateReferenceAssembly requires that alias to match the explicit core and writes canonical CLI Char signatures. This declaration projection cannot represent native multi-scalar grapheme values as CLR char values; it is not an executable value conversion. Direct native imports retain the metadata identity without generating a CLI projection.

C# checks cover CLI scalar/vector signatures and execution, native materialization and reimport, CLI projection, grapheme execution and invalid alias/receiver/owner/result contracts. No metadata version or VM instruction changed. This host API remains covered by this manual reference; the separate guest RavenDoc snapshot is still stale.

Native erased System.Value signatures

AssemblyBuilder.ImportReference retains System.Value as an ordinary scoped value-type reference in the CLI projection. With an explicit native binding for the selected core into the System module, native writing maps that exact nongeneric, top-level System.Value identity to the existing Value signature. AssemblyDefinition.ReadNativeAssembly, NativeAssemblyDefinition.ReadAssembly and signature reimport recover the scoped System.Value identity; no runtime reflection or implicit dependency lookup is involved. Same-named non-core types are not intrinsic carriers. Native Value requires the explicit value alias; malformed/missing aliases and a different projection core are rejected with InvalidDataException. This is an extension of existing signature APIs, not a new API.

The native carrier is independent of the System.Object hierarchy: erased payload type identity must be retained, including for future structural/nominal introspection inputs. The current integration test covers existing Int64 and Byte host outcomes and wrong-kind unpacking. It does not establish all payload categories. Existing runtime storage/depth and lifetime checks still apply; frame-backed references cannot escape by erasure. The CLI reference projection is not a CLR implementation of the erased carrier.

Validation: C# --native-erased-value <seed.neox> <core.dll> checks signature encoding, round-trip import and invalid aliases. The 130 metadata groups remain passing. Raven's bootstrap/verify_erased_values.py independently compiles and imports a generic wrapper, executes real ParseInt64 calls and checks runtime wrong-kind failure. No guest Raven API snapshot signature changed; existing snapshot maintenance blockers remain recorded.

RuntimeAssemblyContainer library PE profile

  • public const int MaxLibraryImageSize = 16 * 1024 * 1024: maximum complete schema-3 library PE image. This is distinct from MetadataArtifactReader.MaxImageSize (4 MiB) and the ordinary structural-reference profile.
  • public static byte[] WriteLibraryBinary(AssemblyBuilder assembly): validates the authored graph and complete external contracts, builds its CLI reference projection, and writes authoritative native metadata in a required schema-3 section. Returns owned unsigned PE32 bytes. Null throws ArgumentNullException; invalid declarations, graph, dependencies, encoding or exceeded bounds throw InvalidDataException.
  • RuntimeAssemblyContainer.Read, ReadCliProjection and AssemblyDefinition.ReadNativeAssembly now accept library schema 3. Native semantic import reads the native declaration graph; ReadCliProjection remains reference-only.

Library transport is bounded to 16 MiB PE, 8 MiB envelope, 32 MiB host JSON, 2,097,152 binary nodes and depth 64. Existing declaration, signature, body and aggregate literal limits remain in force. The ordinary Write/WriteBinary APIs and schema-1/2 readers keep 4 MiB PE/1 MiB envelope bounds. Public NativeAssemblyDefinition.ReadAssembly(JSON) retains its 4 MiB input bound; library container reading uses its bounded internal path. Older runtimes reject the required schema-3 section. Standalone schema-3 transport already existed; this change admits that profile inside the bound PE container.

byte[] image = RuntimeAssemblyContainer.WriteLibraryBinary(builder);
var declarations = AssemblyDefinition.ReadNativeAssembly(image);

C# tests prove legacy writer rejection, >4 MiB library read/projection/native reimport, owned snapshots, over-budget rejection and linked execution. The malformed-schema fixture uses unsupported schema 4, because schema 3 is deliberately supported. 131 metadata groups pass. The combined-source compiler gate separately proves a 53-source native library, unchanged broad application and MemoryStream execution. No public guest Raven signature changed; the manual development reference covers these host C# APIs. No website build or performance claim is part of this change.

Int32 enum authoring and introspection

AssemblyBuilder.AddEnum(string namespace, string name, TypeVisibility visibility = Public) returns a TypeBuilder for a nongeneric top-level enum. It creates the selected core System.Enum base and a Public/SpecialName/RTSpecialName Int32 value__ field. TypeBuilder.AddEnumMember(string name, int value) returns a literal FieldBuilder; its definition has Public/Static/Literal/HasDefault flags and the owning enum signature. Aliases and unnamed integer values are valid. Names must be unique ASCII identifiers. TypeBuilder.Fields retains its existing instance-storage meaning; all declarations, including literals, are available through TypeBuilder.Definition.Fields.

Manual definitions use the same validation path: attach a sealed TypeDefinition extending the explicit core System.Enum, with value__ attributes 0x606 and Int32 signature, then add fields with attributes 0x8056, the attached enum signature and an Int32 constant. The existing three-argument FieldDefinition constructor is retained; the four-argument overload accepts object? constant. Constants require literal flags; ordinary fields cannot carry one. Duplicate or invalid declarations throw ArgumentException; invalid final enum shapes throw InvalidDataException on writing. Flags, other widths, generic/nested enums, interfaces and enum-owned methods/properties are unsupported by this authoring profile. Existing runtime/frontend flags support is unaffected.

TypeDefinition.IsEnum, TypeBuilder.IsEnum and introspection NominalTypeInfo.IsEnum report enum declarations. FieldDefinition.IsLiteral and introspection FieldInfo.IsLiteral identify static literals; their object? Constant returns a supported Int32 constant or null. CLI readers retain other raw signature bytes; this does not expand CLI nominal field-signature decoding. Native readers project canonical nominal literal signatures and reject unsupported enum shapes.

AssemblyBuilder.CreateEnumReference(AssemblyIdentity dependency, AssemblyIdentity dependencyCoreLibrary, string artifactSha256, string namespace, string name) authors a public output-owned enum identity from symbol/host facts. It has the same identity, digest and dependency validation as CreateValueTypeReference. It does not load a dependency. ImportReference of a native enum definition registers its enum category as well. Actual native dependency linking/verification remains required.

IILGenerator.ConvertToEnum(SignatureType enumType) consumes Int32 and produces the nominal enum; ConvertFromEnum performs the inverse. MethodILGenerator implements both. Foreign operands and non-enum signatures reject; stack validation checks operands. CLI emission requires no instruction because the evaluation stack carries the underlying integer. Native emission uses existing newobj and conv.i4 with nominal enum storage. These are semantic helpers, not new raw opcodes or a format-version change.

Validation: the C# enum contract group covers builder/manual parity, CLI execution, native/CLI declaration round trips, facade facts and malformed metadata rejection. --enum-runtime additionally loads a separately encoded native library and consumer. The paired Raven bootstrap/verify_enums.py driver compiles the unchanged TaskState source and exercises mutation, array storage, comparisons and integer conversions on both targets. No guest public API is added; the existing guest snapshot maintenance blocker is unchanged.

Native function identity clarification (2026-10-04)

Native metadata encodes a function type as Function { parameters, returns, no_result }. It does not identify a nominal delegate class. The introspection load context interns resolved shapes: equal ordered parameter/result identities and the return convention share a FunctionTypeInfo instance within that context. Different contexts retain separate views. Function objects carry callable targets and optional bound receivers; neither participates in type identity, and the metadata facade cannot invoke them. Raven's current Func/Action symbol transport is a compiler adapter, not native identity. Inhabited unit and no-result invocation remain distinct. Where Raven converts a no-result method to a unit-producing callback, the native emitter generates an output-owned adapter that invokes the original callback and produces the configured unit value. This allocates an adapter/closure; it is not runtime signature coercion.

Authored Self implementation contracts (2026-10-04)

AssemblyBuilder.CreateMethodReference accepts SignatureType.Self for an authored interface's instance contract, including nested supported signature shapes. A nominal class method contract containing Self is rejected with InvalidDataException. Existing ownership, completeness and signature-scope validation still applies.

When writing an implementing class/value type, required interface methods substitute Self with that implementing type (the open construction for a generic owner). This applies to local and output-owned external interface contracts, including inherited requirements and arrays/constructions. Wrong concrete parameter/result signatures fail with InvalidDataException before output publication. The interface metadata retains Self; the implementation's declared methods use concrete signatures. This is conformance validation, not an implicit conversion or a new dispatch opcode. Executable CLI output with symbolic Self remains unsupported; native SelfType encoding is unchanged.

Floating-point signatures and IL generation

PrimitiveType.Single and PrimitiveType.Double represent CLI binary32/binary64 signature types. Readers retain these identities in methods, fields and properties; value-type generic constraints admit both. No nominal wrapper type is introduced.

The public IILGenerator returned by MethodBuilder.GetILGenerator() provides:

void LoadConstant(float value);
void LoadConstant(double value);
void Emit(OpCode opCode, float operand);
void Emit(OpCode opCode, double operand);

The raw overloads require Ldc_R4 and Ldc_R8, respectively; an incompatible opcode throws ArgumentException without appending an instruction. Constants retain their IEEE bits, including signed zero, infinities and NaNs. Operandless Emit accepts Conv_R4 and Conv_R8; the existing integer conversions also accept floating inputs. This is unchecked numeric conversion, not a guarantee for out-of-range conversions.

Flow validation admits matching Single/Double arithmetic, remainder, negation and Ceq/Clt/Cgt comparisons. Mixed numeric types require explicit conversions. Bitwise operations and shifts still reject floating operands with InvalidDataException before output is returned. CLI output uses the standard signatures and opcodes; native output uses the existing Single/Double types and neoIL instructions.

Native literals store integer bit patterns, not JSON/CBOR floating-point values. RuntimeAssemblyContainer.WriteBinary(AssemblyBuilder) chooses existing schema 3 when a Double literal needs the full UInt64 range (including negative zero). Otherwise it retains schema 2. The application host-image size limit is unchanged. The native-bytes overload continues to require schema-2-compatible input; WriteLibraryBinary always uses schema 3. Older schema-2-only readers reject schema 3. No runtime or format-version change is introduced by this writer extension.

FloatingPointChecks exercises CLI and native signature round trips, literal overload validation, invalid bitwise operations and .NET execution. Set NEOCLR_FLOAT_ARTIFACT when running the C# tests to save the matching executable native assembly, then run it with neoCLR and the explicit System seed. Success exits 42 after arithmetic, NaN and signed-zero checks. This does not establish Raven floating-point code generation or complete compilation of the Single/Double class-library sources.

Unordered floating comparisons

IILGenerator.Emit(OpCode.Clt_Un) and Emit(OpCode.Cgt_Un) consume two matching numeric operands and produce Boolean: unsigned integer less/greater, or floating less/greater respectively, or true if either floating operand is NaN. CLI output uses clt.un/cgt.un; native output uses the same existing instructions. Operand-bearing overloads reject these opcodes with ArgumentException.

Combining Cgt_Un with Boolean negation implements ordered <=, and Clt_Un with Boolean negation implements ordered >=. The floating metadata C# contract executes NaN in both Double operand positions and Single NaN on .NET and NeoCLR. The Raven driver gate separately validates all six source comparison operators.

Static interface contracts and inherited Self

TypeBuilder.AddInterfaceMethod(string name, MethodSignature signature, bool isStatic) adds a public bodyless contract, allowing nongeneric static members alongside existing instance members. The original two-argument overload retains instance behavior. Static properties reuse AddProperty with static accessors. Invalid owners throw InvalidOperationException; invalid/duplicate signatures throw ArgumentException. Instructions or locals on abstract methods fail write validation with InvalidDataException.

Detached MethodDefinition accepts Public | Static | Abstract | Virtual | NewSlot, with the same attachment and signature validation. CreateMethodReference accepts static authored interface contracts; the host still supplies and completes the entire contract explicitly. Required implementations match static/instance classification, visibility, name and substituted parameter/result types. An instance method cannot satisfy a static requirement, nor the reverse. Missing/wrong implementations fail before writing output. CLI output includes MethodImpl rows for static implementations; native output uses existing bodyless static interface declarations, without virtual instance dispatch flags. Symbolic Self still requires native output or a CLI reference projection, not executable CLI Self semantics.

An interface may inherit a local or explicitly scoped external construction such as ComparableTo<Self>. Classes cannot declare unbound Self inheritance. Reader and introspection views retain that scoped Self argument; declaration/constructed owner views supply the scope, and conformance substitutes the concrete implementer. No generic parameter is added. The facade does not load code or invoke contracts.

StaticInterfaceChecks verifies definition/builder parity, local/external static conformance and rejection, inherited Self views, native round trips, and observable .NET constrained static dispatch. The API-authored native program exits 42. The Raven Number gate additionally executes actual source contracts across three native assemblies. Compiler generic callself emission and intrinsic primitive ownership remain separate work; this authoring support does not claim they are complete.

Fixed-width integer signatures and unsigned instructions

PrimitiveType.SByte, Int16, UInt16, UInt32 and UInt64 complete the eight fixed-width integer signatures alongside Byte, Int32 and Int64. They can be used in method results/parameters, fields, properties, vectors, generic arguments and IILGenerator.DeclareLocal(PrimitiveType). The local overload also accepts Single and Double; Void and undefined enum values reject with ArgumentException. Readers preserve exact storage types. CLI signatures use the standard element codes; native signatures use existing primitive names without a new format version.

Evaluation normalizes SByte/Byte/Int16/UInt16/UInt32 to Int32 and UInt64 to Int64 bits, as CLI does. Storage and by-reference element identities remain exact. Unsignedness is an instruction property, not inferred from a stack value's storage signature.

Operand-free IILGenerator.Emit(OpCode) additionally accepts:

Opcode Input and result
Conv_I1, Conv_I2 Numeric input, low signed 8/16 bits sign-extended to Int32
Conv_U2, Conv_U4 Numeric input, unsigned 16/32-bit conversion, Int32 evaluation bits
Conv_U8 Numeric input, unsigned 64-bit conversion; zero-extends Int32 bits
Conv_R_Un Int32/Int64 bits interpreted unsigned, converted to Double
Div_Un, Rem_Un Two matching integer evaluation types; unsigned quotient/remainder
Shr_Un Integer and Int32 count; zero-filled right shift
Clt_Un, Cgt_Un Matching integers compared unsigned, or matching floats with unordered semantics

These emit standard CLI opcodes and existing native instructions. Floating operands for unsigned division, remainder, shift or Conv_R_Un reject during body validation; integer width mismatches likewise reject. Conversion to UInt64 from a signed Int32 requires sign extension with Conv_I8 when that is the source-language contract. Use Emit(OpCode.Ldc_I8, longBits) for 64-bit integer constants.

IntegerWidthChecks.cs executes the same authored program on .NET and NeoCLR, including high-bit arithmetic, conversion and signature round trips. The separately compiled Raven integer gate covers native import, fields/properties, arrays and generic calls. This does not yet make source-owned primitive Number implementations or generic Number-constrained dispatch complete.

Native numeric declaration representation

TypeDefinition.NativePrimitive, TypeBuilder.NativePrimitive and introspection NominalTypeInfo.NativePrimitive return PrimitiveType?. Non-null means that the native declaration implements that canonical runtime scalar. Null means ordinary metadata; a CLI System name alone never establishes native ownership.

TypeDefinition.SetNativePrimitive(PrimitiveType primitive) works on authored (including detached) definitions. TypeBuilder.SetNativePrimitive forwards to the same validation. The declaration must be the matching System.<primitive> sealed, sequential, nongeneric, top-level value type with no record fields or constructors. Only the ten fixed-width integer/floating primitives are admitted. Other categories, wrong names, conflicting designations or incompatible storage throw ArgumentException; loaded snapshots throw InvalidOperationException. The writer revalidates after edits, so adding fields or constructors later cannot bypass the contract.

var scalar = assembly.AddValueType("System", "Double");
scalar.SetNativePrimitive(PrimitiveType.Double);
var read = scalar.AddInstanceMethod("Identity", new(PrimitiveType.Double, []));
var il = read.GetILGenerator();
il.LoadArgument(0); // managed address of Double, not an ordinary record
il.LoadObject(PrimitiveType.Double);
il.Return();

An owned scalar's signature and implementing Self are the primitive signature. Native output uses existing canonical System names, scalar owners, Runtime representation and managed receiver instructions. No new native instruction or metadata version is introduced. The snapshot and introspection preserve this fact; importing a native method preserves its exact assembly dependency and scalar receiver. No runtime code or reflection API is loaded during import.

Executable CLI output rejects native primitive declarations and calls to their imported members with InvalidDataException: these are not ordinary structs hosted in another .NET assembly. Reference-only CLI projections remain available for diagnostics; only authoritative native snapshots retain NativePrimitive. This follows the CLR's separation of intrinsic scalar storage from ordinary value layouts without claiming that an arbitrary .NET library can replace core numeric types.

The designation does not supply runtime storage fields, resolve dependency ownership, or rewrite a source m_value field. A compiler must select ownership explicitly and translate its checked intrinsic-storage contract into receiver operations. Duplicate canonical primitive owners remain invalid at runtime linking. Raven source primitive integration and generic Number constraints are not established by this API alone.

PrimitiveRepresentationChecks covers detached/builder authoring, strict malformed input, immutable snapshots, introspection, late invalid edits and independent native method import. With NEOCLR_PRIMITIVE_ARTIFACT and NEOCLR_PRIMITIVE_CONSUMER set, the C# suite saves a primitive library and consumer; running the consumer with that module and the explicit seed returns 42 after mutation through its primitive receiver.

AssemblyBuilder.CreateMethodReference also accepts optional PrimitiveType? nativePrimitive = null. Supply the same explicit numeric designation for every member of an output-owned canonical System value reference. This authors scalar receivers and dependency records using only identity/signature facts; it does not reopen reader definitions or validate the dependency's implementation. Invalid names, nesting, arity, constructors or overrides throw ArgumentException; conflicting primitive/nominal owner contracts throw InvalidDataException. Ordinary references keep the null default. Runtime linking verifies the supplied dependency. Executable CLI output rejects these native calls. PrimitiveRepresentationChecks now also saves NEOCLR_PRIMITIVE_CONSUMER + ".authored.neox", an independently executable consumer created through this symbol-facts-only path.

Native primitive definitions and authored member references use canonical runtime member names, such as System.Int32.CompareTo, so seed-facing primitive calls retain their ABI spelling. The native reader accepts the preceding encoded member spelling as well and retains each artifact's actual callable/accessor names. This does not change signatures, opcodes or container version. Numeric interface resolution uses the declaration origin name when needed; exact type, visibility and parameter-mode contracts are still validated. Existing libraries must be rebuilt when ownership moves from the implicit System seed to a separately referenced source library.

Earlier experimental metadata readers that require encoded primitive member names must be upgraded before reading newly emitted canonical members. Existing runtime container and instruction formats are unchanged.

Raven’s symbol-authored primitive references use the new canonical ABI. Rebuild older experimental primitive-provider artifacts for that path; reader-mediated ImportReference continues to preserve the older artifact’s executable name.

Static constrained interface dispatch

IILGenerator.CallConstrained(implementingType, staticInterfaceMethod) and Emit(OpCode.Call, implementingType, staticInterfaceMethod) now author the static counterpart of the instance operation above. The implementing type is an output-owned, nongeneric class or value type, including explicitly designated native numeric types. The interface and its nongeneric method must be owned by the same output assembly; external/constructed contracts and open method/type parameters remain unsupported.

var il = main.GetILGenerator();
il.LoadConstant(42);
il.CallConstrained(implementation, interfaceEcho);
il.Return();

This consumes the declared arguments and produces the declared result, without a receiver value or address. The writer checks the complete interface implementation. Self inside parameter/result signatures substitutes the implementing type, including nested signature shapes already supported by implementation conformance. Invalid stack operands fail writing with InvalidDataException. Invalid opcodes or ownership/conformance fail before the instruction is appended with ArgumentException; null operands use ArgumentNullException. The current instruction-count limit remains in force.

The CLI writer emits standard constrained. followed by call; the native writer uses existing nonborrowed callself. Native Self signatures still cannot be emitted as an executable CLI assembly. C# tests execute ordinary static contracts on .NET and save native ordinary/Self artifacts via NEOCLR_STATIC_ARTIFACT (the Self image appends .self.neox). Both native artifacts return 42. This is a metadata-generator capability, not yet support for generic Number-constrained Raven programs. No schema or runtime instruction change is introduced.

Method interface bounds

Model.GenericMethodInterfaceConstraint(int ParameterIndex, TypeReference InterfaceType) records a zero-based method type parameter ordinal and a local or external nongeneric interface reference. MethodDefinition.InterfaceConstraints and MethodBuilder.InterfaceConstraints expose read-only lists of these records. Define bounds using:

void MethodDefinition.AddInterfaceConstraint(int parameterIndex, TypeDefinition interfaceType);
void MethodDefinition.AddInterfaceConstraint(int parameterIndex, TypeReference interfaceType);
void MethodBuilder.AddInterfaceConstraint(int parameterIndex, TypeBuilder interfaceType);
void MethodBuilder.AddInterfaceConstraint(int parameterIndex, ImportedTypeReference interfaceType);

The builder delegates to the canonical definition. Detached definitions may be attached later; writing revalidates module ownership. A null interface throws ArgumentNullException; invalid ordinal, duplicate, foreign attached owner, noninterface, generic interface or more than 128 bounds throws ArgumentException. Loaded snapshots are immutable and reject mutation with InvalidOperationException. Unsupported loaded constraint categories cause InterfaceConstraints to throw InvalidDataException rather than return a partial contract.

Introspection.MethodGenericParameterTypeInfo.GetInterfaceConstraints() returns IReadOnlyList<NominalTypeInfo> using canonical views in the same metadata load context. External bounds resolve through the explicit dependency catalog and must resolve to nongeneric interfaces. Missing/wrong dependencies or noninterface bounds throw InvalidDataException. No implicit dependency loading occurs. Method construction in introspection substitutes signatures; language admission and constraint satisfaction remain compiler responsibilities.

MethodBuilder.MakeGenericInstance checks concrete owned arguments against every bound; writing repeats this validation so later edits cannot invalidate an existing call silently. Method-parameter forwarding is now checked against the caller bounds at emission; see the external dispatch update below. Constructed argument satisfaction remains bounded by supported explicit interface conversions. AssemblyBuilder.ImportReference(MethodDefinition, ...) rejects bounded methods with NotSupportedException until its contract can preserve their bounds. Unconstrained imports retain their previous behavior.

CLI output uses GenericParamConstraint rows referencing interface TypeDefs or scoped TypeRefs. Native output uses existing function generic_constraints / TypeBound records. Native snapshots retain both bound kinds. The legacy reference-only CLI projection preserves local bounds and rejects external bounds with NotSupportedException; use direct native import. No runtime schema change is required; older experimental readers may reject the added function field. C# tests cover builder/definition parity, executable CLI output, native/projection round trips, canonical views, invalid ordinals/duplicates and late graph mutation. A native API-authored bounded method executes with exit 42. This does not yet enable Raven's Number-constrained generic bodies or calls.

External method bounds require a reference registered through CreateInterfaceReference, with an explicit dependency identity/core/digest and CompleteInterfaceReference before writing. Both definition and builder overloads use this output-owned contract; they do not reopen importer objects. Definition-level external bounds require an attached method. Foreign/unregistered references, duplicates and generic bounds reject. Concrete local arguments may satisfy external bounds through their declared interface relationships; method-parameter forwarding is now checked at emission. Direct snapshot import of bounded methods remains unsupported; see the symbol-authored call-reference distinction below.

Migration (development only, 2026-10-04): GenericMethodInterfaceConstraint.InterfaceType is now TypeReference. Use MetadataLoadContext.Resolve for canonical views or an explicit resolver for TypeReference.Resolve. The TypeDefinition authoring overload is retained. Separate contract fixtures execute on .NET and NeoCLR; the direct Raven importer checks valid/invalid arguments and canonical external symbol identity without a CLI projection.

Open constrained static calls

The independent metadata IILGenerator, returned by MethodBuilder.GetILGenerator(), exposes these additional overloads:

void CallConstrained(SignatureType implementingType, MethodBuilder target);
void Emit(OpCode opCode, SignatureType implementingType, MethodBuilder target);

implementingType must be SignatureType.MethodParameter(index) in the body's method scope. The parameter must have an owned nongeneric interface bound admitting the target interface, directly or through inheritance. target must be an owned nongeneric static abstract interface method. Raw Emit accepts only OpCode.Call. Null operands throw ArgumentNullException; missing bounds, invalid scope, foreign targets, instance methods and unsupported opcodes throw ArgumentException before adding an instruction. Writing revalidates the operands and the body stack.

Self in the target signature substitutes the method parameter for argument/result verification, including supported nested signature shapes. CLI emits standard constrained. with an MVAR TypeSpec followed by call. Native output uses the existing nonborrowed callself operation with MethodTypeParameter. No runtime or metadata format change is required. The earlier TypeBuilder receiver overloads retain their existing behavior.

Tests execute a generic static-interface call on both .NET and NeoCLR. A separate native Self fixture instantiates the method with Double, adds 20 and 22 and returns exit 42. Typed/raw calls and inherited bounds are covered. Type-owner parameters and open instance calls are outside this owned-target overload. The subsequent external overloads and Raven integration are documented below. CLI Self representation is not introduced by this API; the portable CLI fixture uses ordinary scalar signatures.

External constrained dispatch and Number integration

Additional IILGenerator overloads are available beside the owned-target overloads:

void CallConstrained(SignatureType implementingType, ImportedMethodReference target);
void Emit(OpCode opCode, SignatureType implementingType, ImportedMethodReference target);
void CallConstrained(SignatureType implementingType, ImportedConstructedMethodReference target);
void Emit(OpCode opCode, SignatureType implementingType, ImportedConstructedMethodReference target);

The implementing operand is an in-scope method parameter. The nongeneric external reference overload accepts static nongeneric abstract interface contracts and Call. The constructed reference overload accepts a completed constructed interface contract, with no method arguments, using Call for static methods and Callvirt for instance methods. Instance calls consume a managed receiver address followed by their explicit arguments. The caller's method bounds must entail the target interface. Traversal substitutes Self with the implementing parameter, so Number's ComparableTo<Self> relationship admits CompareTo on ComparableTo<!!0>. Contract identities, declaring arguments and methods remain output-owned. No importer or runtime reflection object is retained.

Null operands throw ArgumentNullException. Unsupported scope, foreign references, missing bounds, wrong opcode or target category throw ArgumentException. Incomplete contracts or excessive relationship traversal throw InvalidDataException. Validation repeats before writing; stack argument/result mismatches reject before publication. Standard CLI constrained./call or constrained./callvirt and existing native callself encode these calls. No native format or runtime behavior change is required.

MethodBuilder.MakeGenericInstance now permits provisional method-parameter arguments. Call emission validates the forwarding caller's scope and bounds; writing rechecks them. Creating a reference alone does not prove that an arbitrary caller can use it. Concrete arguments still validate at reference creation. Generic owner-parameter forwarding and special method constraints remain unsupported. The direct snapshot convenience overload ImportReference(MethodDefinition, ...) still rejects bounded methods; Raven authors ordinary call references from validated symbol contracts, retaining the bounds in the producer's method definitions as CLI metadata does.

void AssemblyBuilder.SetNativePrimitive(ImportedTypeReference type, PrimitiveType primitive);

This explicit host assertion binds an output-owned external numeric value declaration to its canonical scalar category. It requires a nongeneric top-level System type whose name matches one of the ten numeric PrimitiveType values. The reference already carries its exact dependency identity/core/digest. A null reference throws ArgumentNullException; a foreign or incompatible reference throws ArgumentException; a second dependency owning the same scalar throws InvalidDataException. Repeating the same designation is idempotent. Declared interface conversions can then prove scalar generic arguments satisfy bounds. This does not infer primitive ownership merely from an arbitrary metadata name.

C# tests execute external static and constructed instance calls plus bounded forwarding on .NET and NeoCLR. The native compiler gate independently rebuilds numeric sources, imports them into a generic algorithms library, and imports both emitted libraries into a source-free consumer covering every Number member across all ten numeric types.

Explicit interface bodies

public sealed record ExplicitInterfaceImplementation(
    InterfaceImplementation Interface, string MemberName);
IReadOnlyList<ExplicitInterfaceImplementation> MethodDefinition.ExplicitInterfaceImplementations { get; }
void MethodDefinition.AddExplicitInterfaceImplementation(InterfaceImplementation contract, string memberName);
void MethodBuilder.AddExplicitInterfaceImplementation(TypeBuilder contract, string memberName, params SignatureType[] arguments);
void MethodBuilder.AddExplicitInterfaceImplementation(ImportedTypeReference contract, string memberName);

These APIs map a private concrete nongeneric instance body to a member of an interface implemented by its declaring type, including inherited and constructed external contracts. Interface preserves the output-owned declaration and copied generic arguments; MemberName is the declared method name (get_Count for a property getter). The body's signature selects the overload. Builders delegate to the same definition validation. External references require the existing complete, explicitly supplied interface contract. No importer or runtime reflection object is reused and no dependency is implicitly loaded.

Null contracts throw ArgumentNullException. Invalid visibility/category, foreign references, duplicate mappings and invalid scopes throw ArgumentException. Detached or loaded definitions cannot be edited (InvalidOperationException). Writing rejects missing members, incompatible signatures or multiple bodies for the same interface slot with InvalidDataException. Mappings are limited to 128 per body; generic explicit methods and static explicit bodies are outside this profile. Call method.GetILGenerator() to emit the body separately.

CLI output uses standard MethodImpl rows and private/final/virtual/newslot bodies. Native output uses the existing scoped interface_implementations contract and runtime dispatch; there is no new metadata version. Native snapshots expose mappings and method flags. CLI snapshot MethodImpl materialization remains unsupported: reading this property throws NotSupportedException. Native reference-only CLI projection also rejects these mappings rather than silently discarding them; direct native semantic import is supported.

Qualified explicit property names are descriptive metadata names; actual accessor identity, visibility and signatures remain validated independently. The runtime permits bounded ASCII qualification used by Raven, not arbitrary new identifier syntax. C# contracts cover definition/ builder parity, two same-named interface slots, native round trips, private CLI dispatch, external generic diamond contracts and incompatible implementations.

Runtime-owned String declaration

TypeDefinition.SetNativePrimitive(PrimitiveType.String) and the corresponding TypeBuilder convenience method now designate the canonical nongeneric top-level System.String reference declaration. Numeric designations still require value types. String must be a nonabstract, noninterface class with no fields or static constructors. Instance constructors are supported through AddConstructor and ordinary .ctor definitions. The same validation repeats at write time. Wrong category, identity, storage or conflicting designation throws ArgumentException; loaded definitions remain immutable.

AssemblyBuilder.SetNativePrimitive(ImportedTypeReference, PrimitiveType.String) and CreateMethodReference(..., nativePrimitive: PrimitiveType.String) accept an output-owned external String reference. They retain the existing explicit dependency identity, core and digest requirements. No declaration is inferred from its name alone. Foreign/wrong-category references reject; conflicting owners reject with InvalidDataException.

String instance bodies receive the string reference directly: LoadArgument(0) is the storage value. Do not use the numeric managed receiver's ldobj/stobj convention. Native encoding uses the existing Runtime representation, String signature and System.String identity. Its is_reference_type field describes ordinary record-class semantics, so is false for this runtime-owned representation; the reader derives String's reference category from its canonical Runtime identity. No format version or runtime instruction changed. Native snapshots retain NativePrimitive=String and IsValueType=false. Executable CLI writing still rejects native primitive implementations; this is not a host System.String replacement. Char remains outside this API and retains its grapheme representation.

C# tests cover definition/builder category parity, native round trips, invalid value-type String designation and explicit external method references. Native local and separately encoded consumer calls execute with reference receivers. The fixture uses an empty System seed to exclude competing String ownership; it is a metadata contract test, not the full Raven class-library bootstrap gate.

Owned native grapheme declaration

bool TypeDefinition.NativeGrapheme { get; }
void TypeDefinition.SetNativeGrapheme();
bool TypeBuilder.NativeGrapheme { get; }
void TypeBuilder.SetNativeGrapheme();
void AssemblyBuilder.SetNativeGrapheme(ImportedTypeReference type);
bool NominalTypeInfo.NativeGrapheme { get; }

SetNativeGrapheme designates the canonical top-level, nongeneric System.Char value declaration as runtime-owned Unicode grapheme storage. It must have sealed sequential value-type attributes, no fields and no constructors. Builder convenience delegates to exactly the definition validation. Wrong identity, category or storage throws ArgumentException. Loaded definitions throw InvalidOperationException. Writing revalidates so adding a field after designation cannot bypass the contract. Repeated designation is idempotent. NativePrimitive remains null: no numeric or UTF-16-code-unit category is added.

A local Char signature uses the owning nominal declaration in the API and the existing native Char signature in the artifact. Instance bodies receive a managed value address: LoadArgument(0), LoadObject(characterDefinition), Return() preserves the whole grapheme. The native reader and introspection facade retain NativeGrapheme, IsValueType and canonical signature identity. Native Runtime representation and System.Char callable names are reused; no format-version change is needed.

Executable CLI output rejects this native storage designation. Ordinary imported .NET Char and its UTF-16 code-unit signature remain unchanged. This does not replace the .NET char contract. Native snapshot ImportReference(TypeDefinition/MethodDefinition) preserves the storage designation. For emission from independent semantic facts, create an output-owned System.Char value reference with the dependency identity, core and artifact digest, call AssemblyBuilder.SetNativeGrapheme(reference), then CreateMethodReference. This loads no metadata. Repeated designation of the same reference is harmless. Null throws ArgumentNullException; foreign references and incompatible identity/category throw ArgumentException. Conflicting owners and designation after ordinary method authoring throw InvalidDataException. Native writing also rejects competing local/external owners. Constructors, overrides and numeric primitive reinterpretation are unsupported on authored grapheme methods. The caller supplies complete signature facts; runtime linking validates them against the actual dependency. Native binding tables retain the external assembly scope, and introspection resolves it through the explicit metadata catalog.

Raven source-owned Char provider selection uses this designation. This API does not silently reinterpret an ordinary .NET Char reference as a grapheme.

The API contract test authors the type and a managed receiver method, round-trips its metadata and executes a separate neoIL caller with combining-mark and ZWJ emoji graphemes. The caller uses an empty System seed without a competing Char declaration. It is not proof of the full source-built Char class library. Unicode text is the text model; grapheme values preserve complete text, while UTF-8 is its native encoding.

Runtime String construction and bootstrap Char signatures

Owned String constructors return Void and retain standard instance .ctor flags and parameter signatures. Their IL generator may StoreArgument(0) to replace the private construction receiver with a String. Other instance methods still reject receiver stores. NewObject returns the completed immutable String; empty construction starts with empty text. Numeric primitive and grapheme constructors remain rejected. Native snapshots retain constructor classification; both imported and independently authored String constructor references are supported. Executable CLI output remains unsupported for native storage.

When a System native bootstrap is explicitly bound, imported CLI Char signature elements resolve to the graph's designated local/external grapheme owner, including inside vectors. With no such binding, Char preserves its original CLI core scope even if the output also declares a native grapheme type. This is a bridge signature rule, not implicit loading or a new .NET Char representation.

Native class-base reader views

C# namespace NeoCLR.Metadata.Experimental.Introspection:

  • NominalTypeInfo.BaseType: TypeInfo? resolves a recorded native class base to the canonical same-context view. Null means the native declaration has no explicit base. The initial supported shape is a local, top-level, nongeneric reference class base of a local, top-level, nongeneric reference class. This does not enumerate inherited members, synthesize System.Object, load files or instantiate runtime objects.
  • Reading this property on CLI snapshots throws NotSupportedException: their base relationships are not yet materialized. Do not interpret absent reader support as proof of no inheritance. Constructed/external native bases remain unsupported and reject when the snapshot is read.

C# namespace NeoCLR.Metadata.Experimental.Model:

  • Existing TypeDefinition.BaseType: TypeReference? retains those loaded native bases as owned definition references. Resolve() returns the original parent definition. Authored behavior is unchanged; loaded CLI base decoding remains pending.
  • AssemblyDefinition.ReadNativeAssembly(ReadOnlySpan<byte>) also accepts standalone schema-2/3 NEOX images containing the supported assembly manifest, in addition to PE/#Neo. General module inventories without that manifest remain unsupported. Write() on an immutable snapshot copies the original container; it does not convert NEOX to PE or reconstruct an editable graph. Existing bounds and validation apply.
  • Missing targets, cycles, static/value/interface/primitive bases and unsupported generic/external relationships throw InvalidDataException. The native reader does not validate opaque method bodies; runtime verification remains required.
  • NativeAssemblyDefinition.CreateReferenceAssembly throws NotSupportedException for these inherited declarations until the writer can preserve them. Container writers that require that projection also reject; none silently flatten the hierarchy.

Validation: ClassBaseReaderChecks covers definition/facade identity, snapshot copying, missing/self/cyclic/unsupported bases and explicit rejection of lossy projection and unmaterialized CLI base views. These are .NET-host APIs documented manually here; no guest RavenDoc signature was added. Builder authoring, external/generic base projection, Raven symbols and emission remain subsequent work.

Local class-base authoring

TypeBuilder AssemblyBuilder.AddClass(string @namespace, string name,
    TypeBuilder baseType, TypeVisibility visibility = TypeVisibility.Public);

This overload creates an ordinary nongeneric top-level reference class derived from an already attached class in the same output. Both owners must be ordinary reference classes, without intrinsic representation, generic parameters or nesting. Null bases throw ArgumentNullException; unsupported/foreign bases and invalid declarations throw ArgumentException before attachment. Representation changes that invalidate an existing base relationship reject at write time.

Manual TypeDefinition construction with parent.ToReference() followed by module.Types.Add(definition) uses the same validation. Bases are immutable and must already be attached, so authoring cannot create inheritance cycles. CLI output uses TypeDef.Extends; native output uses the existing base Named relationship. No new format version is introduced. External/constructed base authoring remains unsupported.

IILGenerator.Call(MethodBuilder) and Emit(OpCode.Call, MethodBuilder) now accept a direct base constructor from a derived constructor. Load argument zero, then the constructor arguments, before calling. A normal return requires exactly one base initialization on every path. Receiver escape, field access before base initialization, repeated initialization and incompatible initialization at branch joins reject with InvalidDataException during writing. Constructors of unrelated types and calls from ordinary methods reject at emission with ArgumentException. Allocation continues to use NewObject/Newobj. Native root construction remains implicit; CLI root constructors still receive Object::.ctor, while derived constructors receive only their explicit call.

An initialized derived receiver can be used for inherited field and method access. C# tests execute both manual and builder definitions on .NET, round-trip native PE metadata and reject invalid initialization. --class-base-runtime <runtime> <fresh-dir> executes a generated native PE that returns 42. This does not add virtual methods, protected visibility, closed-hierarchy declarations, or external class import.

Runtime protected constructors and closed class families (2026-10-04)

Runtime metadata::Visibility::Protected serializes as protected in the native method row. It is admitted only for instance .ctor methods with a declaring type. The verifier and interpreter allow calls from that type or its descendants, using resolved definition identities. Unrelated callers and ordinary protected methods, fields, module functions or types reject. The C# authoring API exposes MethodVisibility.Protected for both TypeBuilder.AddConstructor overloads. Manual MethodDefinition declarations accept CLI access bits Family (4) only on instance .ctor declarations. Both paths share signature/owner checks; unsupported protected members throw ArgumentException before attachment. Writer validation rejects unrelated-family constructor operands with InvalidDataException before producing an image. Existing numeric enum values are unchanged; Protected is appended.

CLI output uses ordinary MethodAttributes.Family; native output records protected with origin access Family. Native reader materialization and MethodInfo.Accessibility preserve MetadataAccessibility.Family, including GetConstructors() views. There is no runtime reflection or importer dependency involved in authoring. External class base authoring and general protected methods/fields remain unsupported.

Native record type rows with is_closed_hierarchy: true must describe an abstract, nonsealed reference class. Direct children must share the root's defining assembly and revision. Descendants through an open local child may be external. The existing false default is unchanged; source permits lists remain Raven validation. These checks do not add closed-interface or general sealed-leaf enforcement. See the runtime access contract and executable scope.

Native closed-class authoring and facade (2026-10-04)

TypeBuilder AssemblyBuilder.AddClosedClass(string @namespace, string name,
    TypeVisibility visibility = TypeVisibility.Public);
TypeBuilder AssemblyBuilder.AddClosedClass(string @namespace, string name,
    TypeBuilder baseType, TypeVisibility visibility = TypeVisibility.Public);
TypeDefinition(string @namespace, string name, uint attributes,
    TypeReference? baseType, bool isClosedHierarchy);
bool TypeDefinition.IsClosedHierarchy { get; }
bool TypeBuilder.IsClosedHierarchy { get; }
bool TypeBuilder.IsAbstract { get; }
bool NominalTypeInfo.IsClosedHierarchy { get; }
IReadOnlyList<NominalTypeInfo> NominalTypeInfo.GetPermittedDirectSubtypes();
void AssemblyBuilder.DeclareClassBase(ImportedTypeReference type,
    ImportedTypeReference baseType);

The original four-argument TypeDefinition constructor is preserved. Closed declarations require Abstract without Sealed and a nongeneric top-level reference class; invalid manual definitions throw ArgumentException on attachment before modifying the module. The overload without a base creates a root using the explicitly selected core Object reference. The base-taking overload (development, 2026-10-07) uses an already attached ordinary nongeneric reference class, including the native Object root. It shares manual-definition validation: null throws ArgumentNullException; foreign, generic, interface, static and value bases throw ArgumentException. Invalid visibility/name or duplicate types also reject. Constructors must initialize their direct base; missing initialization or a sealed base rejects during writer validation. Native reader and introspection retain the canonical base independently of family closure. Its constructors may be Protected. Ordinary local children use AddClass(baseType); abstract allocation fails writer validation with InvalidDataException.

Native closed-family flags survive PE/native reader materialization. Facade children are canonical direct BaseType matches in defining-module metadata order; an ordinary native class returns an empty list. CLI snapshots throw NotSupportedException for closure queries because CLI closed-family attributes are not materialized.

Ordinary executable Write rejects native closed-family declarations. Native PE transport retains Abstract in its nonexecutable CLI projection and closure in the authoritative native payload; there is currently no projected closed-family attribute. Generic/nested closed roots and class virtual/abstract methods remain unsupported.

DeclareClassBase records host-provided signature conversion facts for output-owned top-level class definitions in explicitly registered dependencies. The source is an unconstructed definition; the base is a complete nominal signature whose type parameters are scoped to that source. For example, registering Middle<T> with Base<T[]> and Leaf<T> with Middle<T> permits Leaf<int> to Base<int[]>. Substitution follows each edge and also applies when finding inherited interface views for variance. Constructed classes themselves remain invariant.

The method emits no dependency declaration and opens no metadata reader. Repeating the same edge is idempotent. Foreign/value/interface/nested owners, unbound bases, method or out-of-scope type parameters, definition cycles (including expanding constructions), and conflicting edges throw ArgumentException. Null inputs throw ArgumentNullException; over 4096 edges throw InvalidDataException. Supported base arguments are primitive, nominal, array and owner-parameter signatures. Unsupported signature categories remain implementation gaps. Runtime verification checks the actual dependency definitions; hosts must supply truthful symbol facts. This does not yet enable authoring generic class layouts or materializing generic base signatures through the native TypeDefinition reader.

See the executable compiler gate.

Runtime type handles

PrimitiveType.RuntimeTypeHandle is an opaque runtime type identity in signatures, not a user-authored empty struct. CLI encoding is a value-type reference to System.RuntimeTypeHandle in the explicitly selected core assembly; native encoding uses the existing RuntimeTypeHandle category. CLI imports recognize that exact core AssemblyRef identity or a value-type definition inside that exact selected core. The library does not load dependencies or expose host Type objects.

IILGenerator.LoadTypeToken(SignatureType type) and Emit(OpCode.Ldtoken, SignatureType type) push one RuntimeTypeHandle. They accept owned nominal types, constructed nominal types, primitives, vectors and in-scope method/owner generic parameters. Encoding uses CLI ldtoken or native ldtoken. Null throws ArgumentNullException; Void, direct function signatures, byrefs, Self, foreign owners and out-of-scope parameters throw ArgumentException. Token authoring uses the same generator for builders and attached definitions. It does not construct runtime introspection descriptors or promise default-handle/comparison operations.

C# tests check CLI local, constructed, method-generic and owner-generic identity, CLI signature import, native signature round trips and rejected operands. The generated native PE executes local, constructed, vector and instantiated method-parameter tokens, verifies successfully and returns 42. External dependency-token identity and runtime handle-service comparisons remain integration gates.

Runtime internal calls

MethodDefinition.SetInternalCall() -> void marks an authored assembly function with implementation attributes 0x1000. MethodBuilder.SetInternalCall() is a convenience method over the same canonical definition. Both require an empty body, no locals or labels and no type owner. Generic method parameters are preserved. Loaded snapshots, type methods and nonempty declarations throw InvalidOperationException. Setting the same valid declaration again is idempotent. There is no implicit P/Invoke library or entry-point lookup.

MethodDefinition.ImplementationAttributes returns the flag for authored and loaded CLI/native definitions. CLI writing emits MethodDef.ImplFlags and no method body; this does not make an arbitrary InternalCall executable by the desktop CLR. Native writing uses the existing impl_flags field and the exact namespace-qualified service name, rather than an ordinary generated function name. Existing functions keep their encoding. Readers and native reference projections preserve the flag, and imported assembly-function references preserve the runtime service name.

The declaration's supported signature may reference types defined in the same output assembly. That enables a service contract to share ownership with source descriptors; it does not implement their runtime factory. The runtime still checks the exact binding name/signature. A structurally valid declaration with an unknown service writes, then runtime verify/run rejects it. There is no implicit dependency loading or service fallback.

Writing rejects instructions, locals or labels added after marking, and rejects an internal-call entry point with InvalidDataException. Native reading rejects unsupported implementation bits or an internal-call declaration with a body, locals, owner, generic parameters or incompatible abstract/virtual/instance flags. Type-owned and generic internal-call authoring remain outside this bounded profile.

var query = assembly.AddFunction("neoCLR.Runtime", "TypeArgumentCount",
    new MethodSignature(PrimitiveType.Int32, [PrimitiveType.RuntimeTypeHandle]));
query.SetInternalCall();
// Emit calls from ordinary method bodies through their separate IILGenerator.

C# tests cover definitions/builders, CLI/native/reference-projection flags, output-owned nominal result signatures and invalid graphs. Generated native PE executes with an explicit empty test seed, both directly and through a separate native metadata consumer. Unknown runtime services reject. See the integration record.

Runtime execution checkpoint (2026-10-05): native internal-call declarations can now return an output-owned System.Introspection.ModuleInfo interface through TypeModule. The runtime validates and materializes its source-owned provider; see the scope, layout and executable contract. No new C# authoring member is required. This bounded runtime capability does not imply that arbitrary descriptor-returning services or the full production descriptor library are supported.

Closed interface families

AssemblyBuilder.AddClosedInterface(string @namespace, string name, TypeVisibility visibility = TypeVisibility.Public) returns an attached nongeneric top-level interface. Manual definitions use new TypeDefinition(ns, name, 0xa1, null, isClosedHierarchy: true) and the same validation. Invalid names, visibility, duplicates or unsupported categories throw ArgumentException. Native round trips preserve IsClosedHierarchy independently of CLI Sealed; CLI reference flags remain Interface/Abstract. Executable CLI writing rejects the native extension. NominalTypeInfo.GetPermittedDirectSubtypes() includes directly declared interface implementations and derived interfaces, excluding indirect descendants. Runtime linking rejects direct children outside the defining module/revision. Open local branches remain extensible. Generic closed interfaces are not yet authored. Existing local relationship encoding and closed-family flag are reused without a format revision.

Reference Object overrides

TypeBuilder.AddOverride(name, signature) and manual MethodDefinition(name, 0x46, signature) admit nongeneric reference owners alongside value owners. Supported exact slots: String ToString(), Int32 GetHashCode(), Boolean Equals(assembly.CoreObjectType). The flags are Public/Virtual without NewSlot or Abstract. Generic reference owners and generic override methods remain unsupported. Static/interface owners, wrong core Object identity, or incompatible signatures reject on attachment; duplicate members reject.

IILGenerator.CallVirtual(MethodBuilder) and Emit(OpCode.Callvirt, MethodBuilder) also admit these owned reference overrides. Imported references retain RequiresVirtualDispatch. CreateMethodReference(..., isOverride: true) supports the same slots and exact core identity. Value overrides retain managed receivers and direct calls.

Native writes require an explicit System binding with the actual matching public virtual Object slot, and native readers preserve flags. Runtime linking validates the contract; reference dispatch traverses the actual class lineage, including an implicit Object view for rootless native classes. No Object storage fields are introduced. The CLI writer uses ELEMENT_TYPE_OBJECT for the configured core Object signature, including nested arrays/parameters, rather than a nominal CLASS encoding that fails CLR override matching. C# tests execute both manual and builder definitions on CLR; native compiler consumers exercise separate-assembly class, Object-view and inherited dispatch.

Flags enums

TypeDefinition.IsFlagsEnum, TypeBuilder.IsFlagsEnum and Introspection.NominalTypeInfo.IsFlagsEnum report combinable enum values. CLI snapshots recognize the exact core FlagsAttribute without loading dependencies; native snapshots read the existing enum-info flag. Ordinary enums/non-enums report false. Native raw custom-attribute collections do not synthesize a FlagsAttribute: use IsFlagsEnum for the portable declaration fact. Reference projections reconstruct the ordinary core marker.

TypeDefinition.SetEnumFlags() and TypeBuilder.SetEnumFlags() mark attached authored enums through a standard core FlagsAttribute. Calls are idempotent. Loaded, detached or non-enum definitions reject with InvalidOperationException. A manually added CustomAttributeDefinition(module.ImportReference(core, "System", "FlagsAttribute"), []) uses the same writer path. Duplicate/malformed core markers reject with InvalidDataException. Another assembly's similarly named attribute does not set the flags classification. Native writing consumes the standard marker into existing enum-info metadata, without an executable attribute-constructor dependency. No native format revision is required. Supported storage remains Int32; flag names and values retain the normal enum contracts.

Parameter arrays

MethodDefinition.SetParameterArray(int position) and MethodBuilder.SetParameterArray(int position) mark the final by-value vector parameter. Definitions must be attached and authored; loaded/detached methods throw InvalidOperationException, and invalid positions or physical signatures throw ArgumentException. Repeating the same marker is harmless. MethodDefinition.ParameterArrayIndex returns its zero-based position or null. Introspection.ParameterInfo.IsParameterArray exposes the same fact for CLI/native snapshots. The physical signature and calling convention remain ordinary array parameters.

CLI writing uses the standard core ParamArrayAttribute on a Param row. Native writing uses existing custom_attributes with the parameter's metadata target_token, retaining exact native System marker identity through an explicit bootstrap binding. No format extension or implicit dependency loading is introduced. Missing/wrong marker declarations, malformed marker signatures/values and invalid parameter targets reject before publication. The bootstrap marker constructor is executable but is not invoked during metadata import. This marker is recognized by its qualified standard name in CLI metadata; native dependency resolution additionally checks the explicit System alias. Other method attribute categories remain explicitly unsupported in this reader profile.

Inherited interface implementations

TypeBuilder.AddInterfaceImplementation and manually authored TypeDefinition.Interfaces now accept exact public implementations inherited from a local nongeneric base class. Search selects the nearest matching declaration, after an explicitly mapped local method. Only methods actually selected for interface implementation receive CLI virtual/final/newslot flags; unrelated methods retain their existing attributes. Existing exact parameter/return matching and visibility validation apply. Missing implementations reject before writing. Inherited explicit reimplementation is rejected rather than authoring an invalid MethodImpl whose body is outside the declaring type. External class inheritance remains unsupported.

Final classes and Boolean storage

TypeDefinition.SetSealedClass() and TypeBuilder.SetSealedClass() set the ordinary CLI Sealed flag on an attached concrete reference class. They are idempotent and return void. Loaded, detached, static, abstract, value and closed-family definitions reject with InvalidOperationException. Manual TypeDefinition attributes may use the same 0x100 flag; the writer validates both paths. CLI and native readers preserve the flag, and Introspection.NominalTypeInfo.IsSealed reports it. Deriving from a sealed local class rejects before writing. This is finality, distinct from a closed hierarchy.

SetNativePrimitive(PrimitiveType.Boolean) supports the canonical fieldless System.Boolean value declaration. It follows numeric primitive validation and ldobj/stobj scalar storage; native import and introspection preserve NativePrimitive. A name alone does not claim ownership. Executable CLI writing of runtime-owned primitive implementations still rejects; explicit host ownership selects the provider.

Authored type-row budget

AssemblyBuilder type authoring and manual ModuleDefinition.Types attachment admit 4,095 declarations instead of 256. This shares the existing CLI reader budget of 4,096 TypeDef rows, reserving row one for <Module>. Native rows omit that synthetic row and admit the same 4,095 declarations. Nested and top-level declarations share the budget. Authoring beyond it raises ArgumentException; native reading beyond it raises InvalidDataException before materialization. Failed attachment leaves the collection unchanged. No signature, token representation or metadata version changes.

All byte, field, method, property and dependency limits still apply. Large libraries may need RuntimeAssemblyContainer.WriteLibraryBinary rather than the smaller application profile. The limit is a bounded host-library policy, not a CLI format maximum. Older host library versions retain their lower native/authoring cap and reject larger inputs.

Native enum Object behavior

Int32-backed native enums now participate in inherited Object.ToString, Equals and GetHashCode calls through ordinary boxing. ToString uses the existing enum metadata formatter (named values, flags composition and numeric fallback); equality also requires the same nominal enum type, and hashing uses the Int32 payload. This adds no metadata category or guest member signature. The existing enum alias choice remains unspecified for .NET parity; the current formatter prefers the first declared exact alias.

Managed entry arguments

AssemblyBuilder.EntryPoint and authored AssemblyDefinition.EntryPoint admit an optional single SignatureType.ArrayOf(PrimitiveType.String) parameter. Writer and native reader validate the same contract; CLI output retains the normal String[] signature and entry MethodDef token. The native runtime supplies a bounded managed String array at startup. No additional instruction, metadata version, runtime service or compiler-generated wrapper is introduced. Current native name-based entry selection rejects ambiguity between parameterless and String[] overloads.

Rust ExecutionOptions.arguments and Environment retain argv[0]; String[] entry points receive the remaining elements. Hosts should include the program name/path first. Empty options produce an empty array. CLI -- arguments retain their order and Unicode text. Allocation respects array and heap limits and can fail before the entry body. Direct host method invocation continues to use the explicitly supplied arguments. C# EntryArgumentChecks covers CLI invocation and native readback; runtime tests cover empty/nonempty vectors, limits, unsupported shapes and ambiguity. The emitted C# test image executes under neoCLR with two arguments, and the Raven upload sample consumes its URL/mode parameters unchanged.

Source-owned runtime handles

TypeDefinition.SetNativePrimitive(PrimitiveType.RuntimeTypeHandle) and the matching builder method now accept the canonical System.RuntimeTypeHandle declaration: sealed, sequential, nongeneric, top-level value type without fields or constructors. The runtime owns handle storage; do not author an IntPtr payload or an m_value field. Wrong names, reference categories, storage or constructors reject with ArgumentException. Writers revalidate edits. Native reader and NominalTypeInfo.NativePrimitive preserve the RuntimeTypeHandle designation; loaded definitions remain immutable.

This extends the existing primitive contract rather than adding a new signature category. Signatures still use PrimitiveType.RuntimeTypeHandle, encoded as the ordinary CLI core handle reference and the existing native RuntimeTypeHandle category. Executable CLI output of native primitive implementations remains unsupported. Dependency catalogs must select one owner; a source handle cannot compete with a retained seed handle. C# tests cover definition/builder authoring, native round trip, introspection and invalid storage.

Internal-call declarations in separate assemblies

Native loading now admits matching runtime-service InternalCall declarations in distinct assemblies. Each retains its definition identity. Symbolic calls with a local service declaration bind locally; explicit external identities remain exact, including access checks. Duplicate declarations within one module, incompatible service signatures and ambiguous unqualified calls without a local declaration still reject. Registry validation is unchanged: a matching name alone never grants a native service. See the Object service integration gate.

Native Object root authoring

AssemblyBuilder.AddNativeObjectRoot() : TypeBuilder attaches a public abstract, nongeneric, baseless System.Object. For manual authoring, construct new TypeDefinition("System", "Object", 0x81, null), call TypeDefinition.SetNativeObjectRoot() : void, then add it to the module's Types. TypeBuilder.SetNativeObjectRoot() : void uses the same validation. TypeDefinition.IsNativeObjectRoot : bool and TypeBuilder.IsNativeObjectRoot : bool report the authoring designation. Loaded snapshots return false: this flag is not runtime selection. Readers preserve the declaration's name, abstract flags and base.

Designation rejects incompatible names, visibility, generic/nested/value/static/closed shapes and record fields with ArgumentException; loaded definitions reject mutation with InvalidOperationException. Attachment rejects duplicates. Writers revalidate shape and reject later invalid mutations with InvalidDataException.

Native output uses canonical System.Object in the existing format, with no base and no new representation category. Its reference-only CLI projection uses a nil Extends and ELEMENT_TYPE_OBJECT for signatures referring to the authored root. Executable CLI Write() rejects the native designation. Unlike ordinary .NET Object, the current NeoCLR source root is abstract; this API preserves that existing platform contract. The benefit is explicit root identity without a competing bootstrap base; the cost is that this artifact needs NeoCLR host admission and cannot be executed by the CLR.

This is declaration support, not complete core-library production: callers still need boxing/root reference selection and compiler/driver wiring. Root-slot authoring is provided below. CoreObjectType continues to mean the explicit bootstrap reference. No implicit bases or bootstrap references are retargeted by designation. The runtime host must separately select the exact root identity and validate its required slots. Ordinary names do not claim root ownership. See ObjectRootChecks.cs for builder/definition parity, native round trips, CLI signatures, mutation rejection and ordinary lookalike controls.

Native Object virtual slots

TypeBuilder.AddNativeObjectSlot(string name, MethodSignature signature) : MethodBuilder adds a concrete public virtual new slot to the designated root. Supported signatures are String ToString(), Int32 GetHashCode() and Boolean Equals(root), where the last parameter is the exact authored root, not CoreObjectType or another output's root. Use GetILGenerator() on the returned builder for the body. Manual definitions use new MethodDefinition(name, 0x146, signature) followed by attachment to root.Methods. Signature/name errors throw ArgumentException; an incompatible owner or foreign root throws InvalidOperationException during attachment. Duplicate signatures are rejected.

Readers, introspection and CLI reference projections retain Virtual and NewSlot without Abstract or override semantics. Native encoding uses existing is_virtual/is_override fields; no format revision. CallVirtual/raw Callvirt accept owned root slots. An ordinary class or value type cannot claim these new root slots. The existing Object override API continues to reuse inherited slots. As on CLR, declaring a virtual slot is distinct from overriding one; NeoCLR's explicit root admission remains host configuration.

Validation: ObjectSlotChecks covers manual/builder parity, native and CLI round trips, introspection flags and exact Equals identity, malformed declarations and wrong owners. The generated fixture is loaded and executed by Rust object_root_identity; production source Object/compiler integration is still pending.

Selected Object signatures and boxing

AssemblyBuilder.ObjectType : SignatureType returns the explicitly authored native root when present, otherwise the explicitly selected external root or existing bootstrap Object signature. CoreObjectType : ImportedTypeReference keeps its original bootstrap meaning. Declare the root before creating signatures; existing signatures are not rewritten. No dependency is loaded and this property does not select runtime host ownership.

Box and value-type Isinst stack results use ObjectType. Native emission with an authored root validates all three concrete root slots instead of demanding a separate legacy System binding. An incomplete root or a body expecting the unrelated bootstrap Object fails with InvalidDataException before bytes are returned. With an external root, author all three exact slot references through CreateObjectSlotReference before native writing: ToString, Equals and GetHashCode. Missing slots reject with InvalidDataException; a selected name alone is insufficient. The host supplies the contract and the runtime checks the actual linked definitions. Without either selected root, the existing explicit System binding requirement is unchanged.

The API-produced fixture's BoxedDisplay() now emits boxing and virtual dispatch and executes with result "42" under explicit runtime root selection. This tests executable instructions from the API, in addition to the existing source-assembled runtime callers.

Overrides of an authored Object root

TypeBuilder.AddOverride(name, signature) and manually attached MethodDefinition(name, 0x46, signature) support the selected local Object root. Equals must take the exact AssemblyBuilder.ObjectType; a bootstrap or foreign root argument throws InvalidOperationException on attachment. The root itself cannot claim an override of its own slot. Signature selection is revalidated on write, so adding a root after authoring bootstrap-based Equals fails with InvalidDataException.

Native emission requires a complete local root slot contract, or the existing explicit legacy System binding when no root is authored. Overrides preserve CLI Virtual without NewSlot or Abstract. Native readers and introspection retain the Equals parameter's canonical local identity. No new native format fields or runtime dispatch rules are used.

The supported direct builder-to-PE path executes constructors and all three overrides through root slots. Regenerating a CLI projection from a native snapshot with class inheritance remains explicitly unsupported (NotSupportedException); use the original authored graph for PE emission. The normal .NET override execution controls still pass. Raven's source-root planner, virtual declarations and special-type mapping remain pending.

Ordinary abstract classes

TypeDefinition.SetAbstractClass() and TypeBuilder.SetAbstractClass() mark an attached, nongeneric, top-level ordinary reference class with CLI Abstract (0x80). The builder delegates to its canonical definition. Repeated calls are idempotent. They return void and throw InvalidOperationException for detached or loaded snapshots, value/interface/static/sealed classes, nested or generic owners, native Object roots and closed families. Rejected calls leave attributes unchanged.

Manual authoring accepts new TypeDefinition(ns, name, 0x81, baseReference) through the same attachment validation. The base must be the explicitly selected core Object or an attached supported local class. Public/internal visibility is supported. Concrete methods, fields and public/protected constructors retain existing contracts. Direct construction of an abstract owner fails writer validation with InvalidDataException; a concrete subclass can call its base constructor normally.

Native reads preserve Abstract without inventing Sealed, static classification or closed-family semantics. Introspection exposes IsAbstract == true, IsStatic == false, IsSealed == false, and IsClosedHierarchy == false. Static classes continue to require both Abstract and Sealed. The existing payload fields and CLI flags suffice; there is no format-version change. General virtual/abstract method authoring remains unsupported pending the next inheritance slice. No guest class-library API changed.

Local class virtual slots

TypeBuilder.AddVirtualMethod(string name, MethodSignature signature) introduces a public, nongeneric instance slot on a nongeneric reference class. It returns the canonical MethodBuilder; emit its body through GetILGenerator(). AddAbstractMethod(string name, MethodSignature signature) introduces the same slot without a body and requires an abstract owner. Manual definitions use CLI attributes 0x146 (Public | Virtual | NewSlot) and 0x546 (also Abstract), respectively. Invalid names/signatures or duplicates throw ArgumentException; incompatible owners throw InvalidOperationException. Abstract methods reject bodies/locals on write.

AddOverride and manual MethodDefinition(name, 0x46, signature) also support exact local inherited class slots. Writer validation requires matching return/parameter signatures and parameter modes; concrete classes must implement inherited abstract members. Incompatible overrides, hiding an inherited member, or missing implementations throw InvalidDataException before output. General new-slot hiding, generic class slots, re-abstraction, nonpublic virtual slots and external class overrides remain unsupported. Existing value/Object overrides retain their root identity checks.

IILGenerator.Emit(OpCode.Callvirt, method) / CallVirtual(method) dispatch these reference-class slots. Call(method) invokes a concrete base body directly; direct abstract calls are rejected. Reader/introspection flags preserve Virtual, Abstract and NewSlot. Interface conformance includes the local base chain. Explicit virtual slots implementing interfaces are not marked Final. Runtime resolution uses validated metadata member origins to bridge encoded interface names and native slot spellings, while retaining exact owner/signature matching. Existing CLI flags and native payload fields suffice; no version change or implicit dependency loading is introduced.

Raven host catalog boundary

Raven's separate compiler adapter provides NeoClrReferenceCatalog to read an explicit primitive core, native PE references and optional retained runtime seed. This is a compiler-host API, not a member of the metadata library or guest System API. It shares immutable reference instances between semantic import and emission and owns no runtime reflection, implicit dependency search or editor file watcher. The native CLI uses it; the subsequent native project/editor slices below also consume it. See the Raven host API contract for signatures, input limits, failures and snapshot lifetime. No guest API snapshot changes.

Raven native project provider

Raven's optional NeoClrProjectMetadataProvider adapts the native catalog to evaluated projects through the target-neutral IProjectMetadataProvider and immutable ProjectMetadataConfiguration host contracts. These are .NET compiler-host APIs, not guest System.Introspection APIs, so the RavenDoc guest snapshot is unchanged. Their selection, parameters/results, errors and limits are documented in the public host API contract. The metadata reader/writer and importer/emitter boundaries remain independent.

Native project emission and editor lifetime

The host provider's GetConfiguration(projectFilePath) returns a successfully loaded NeoClrProjectConfiguration with Catalog, ReferencePaths, RuntimeSeedPath, Validate(compilation) and CreateEmissionBackend(assemblyName). Target-neutral project/provider interfaces expose explicit metadata input paths for host file watching. Ownership and async contracts are evaluated once per load; emission uses host artifact identities and compiler symbols. Invalid reloads retain the last successful editor snapshot and report failure; builds independently revalidate before atomic publication.

See the complete host API contract for signatures, exceptions, limits and commands. These are compiler-host APIs, not guest System APIs; no RavenDoc guest snapshot or native metadata encoding changes are needed.

Native compiler-host documentation sidecars

File-backed native catalog references expose existing Raven XML/Markdown sidecars through symbol documentation, without changing native metadata or guest APIs. Markdown member help takes precedence over XML; absent/malformed optional sidecars do not invalidate an assembly. Image-only references have no implicit sidecar search. See host options, output rules and editor lifetime. The guest RavenDoc snapshot is unchanged. Website guides are separate content.

Explicit callable nullable annotations

Model.NullableAnnotation(IEnumerable<byte> flags, bool isUniform = false) copies 1–4096 flags into immutable Flags. Values are 0 (oblivious), 1 (non-null) and 2 (nullable), in .NET nullable transform order. IsUniform distinguishes the scalar-byte NullableAttribute constructor, which repeats its flag, from a positional byte-array payload. Uniform annotations require exactly one flag. Null input throws ArgumentNullException; invalid values or lengths throw ArgumentException.

MethodDefinition.SetNullableAnnotation(int position, NullableAnnotation? annotation) and the matching MethodBuilder convenience method share one implementation. Position -1 identifies the return; nonnegative positions identify parameters. Passing null removes the annotation. Invalid positions throw ArgumentOutOfRangeException; detached or loaded definitions cannot be mutated and throw InvalidOperationException. NullableAnnotations exposes the explicit annotations as a read-only dictionary. Attach manually created definitions before setting annotations, just as for parameter metadata.

method.GetILGenerator().LoadArgument(0);
method.GetILGenerator().Return();
method.SetNullableAnnotation(0, new NullableAnnotation([1, 2]));
method.Definition.SetNullableAnnotation(-1, new NullableAnnotation([1, 2]));
// For a string[] signature: a non-null array with nullable string elements.

CLI writing emits ordinary parameter/return custom attributes referencing System.Runtime.CompilerServices.NullableAttribute in the configured core assembly. That core must supply the appropriate byte/byte[] constructors. The CLI reader preserves these explicit payloads; malformed, duplicate or oversized payloads reject. Introspection.MethodInfo.ReturnNullableAnnotation and ParameterInfo.NullableAnnotation expose them without changing physical type views. Absent metadata is not a non-null assertion.

This is raw explicit annotation preservation, not a completed nullable type system. NullableContextAttribute, field/property annotations and general signature-shape validation remain pending. Raven's native adapter now reconstructs supported callable nullable reference, array and generic positions from the facade. Native writing preserves these facts in origin.nullable_annotations; native readers and the compatibility CLI projection retain both scalar and vector forms. Runtime metadata validation checks position, uniqueness and payload bounds without executing an attribute constructor. Loaded-assembly rewriting remains subject to the library's existing limits. There is no new runtime check, layout change or GC policy.

Validation: dotnet run --project tools/metadata/NeoCLR.Metadata.Experimental.Tests -- --nullable-annotations checks authored-definition/builder parity, defensive copying, CLI round trips, facade exposure, malformed input and .NET NullabilityInfoContext interpretation. The generated identity methods execute without changing object identity. See the design and integration boundary.

Native-width integers

PrimitiveType.IntPtr and PrimitiveType.UIntPtr represent signed and unsigned native-width integers in method, field, property and local signatures. Use them in MethodSignature, SignatureType and definition/builder APIs just like the fixed-width integer categories. CLI writers emit standard ELEMENT_TYPE_I (0x18) and ELEMENT_TYPE_U (0x19); readers and introspection preserve the categories. Native metadata uses the existing runtime IntPtr/UIntPtr types. These are integer values, not unmanaged pointer signatures or new inline-array representations.

method.GetILGenerator().Emit(OpCode.Conv_I) and Emit(OpCode.Conv_U) emit conv.i and conv.u. Existing numeric conversions accept native-width integer inputs. The writer rejects nonnumeric operands before publishing bytes. Target width is chosen by the executing runtime; no fixed 64-bit signature is substituted. This support does not add unchecked pointer access or native integer arithmetic validation. The source-provider follow-up also admits SetNativePrimitive(IntPtr/UIntPtr) for their exact canonical System value declarations, with the same no-record-storage validation as other primitive providers.

var identity = owner.AddMethod("Identity", new(PrimitiveType.IntPtr, [PrimitiveType.IntPtr]));
var il = identity.GetILGenerator();
il.LoadArgument(0);
il.Emit(OpCode.Conv_I8);
il.Emit(OpCode.Conv_I);
il.Return();

C# tests compile and execute signed/unsigned conversions, locals and signatures on .NET; the same native artifact verifies and exits 42 under neoCLR. Definition-authored fields, builder-authored methods/properties and introspection retain both categories. No metadata format version changes; older host readers may reject these newly admitted signatures even though the runtime already implements their native categories.

Source-owned erased Value storage

PrimitiveType.Value designates the existing native erased carrier with TypeDefinition.SetNativePrimitive or TypeBuilder.SetNativePrimitive. Create an owned public System.Value value definition, then mark it; generic/nested definitions, record fields and constructors reject as for RuntimeTypeHandle. Use that definition or builder as a signature operand. Converting the bare enum to SignatureType throws ArgumentOutOfRangeException because erased signatures require an explicit owner.

var value = assembly.AddValueType("System", "Value");
value.SetNativePrimitive(PrimitiveType.Value);
var identity = assembly.AddFunction("Identity", new MethodSignature(value, new SignatureType[] { value }));
identity.GetILGenerator().LoadArgument(0);
identity.GetILGenerator().Return();

Native signatures encode Value and the declaration uses existing Runtime storage; CLI signatures retain the owned value-type token. Executable CLI emission rejects native primitive designations. Native reading preserves NativePrimitive and resolves local Value signatures to the canonical local definition. The exact configured core/System bootstrap alias can share evaluation storage with this selected carrier; arbitrary foreign or unmarked local types do not acquire erased storage. No format version change or runtime instruction was added. See the source bootstrap gate and remaining limits.

Intrinsic String over an explicit Object root

AddClass("System", "String", objectRoot) followed by SetNativePrimitive(PrimitiveType.String) retains its canonical Object base when read through AssemblyDefinition.ReadNativeAssembly. Runtime loading requires explicit selection of that fieldless Object root. String retains intrinsic UTF-8 storage, not record fields; unrelated primitive bases remain unsupported. Use GetILGenerator() for constructor bodies, including the direct base call. Runtime evidence.

Expanded library envelope

NativeModuleContainer.WriteLibraryBinary, RuntimeAssemblyContainer.WriteLibraryBinary and runtime write_module select required schema 4 when the encoded library exceeds schema 3's 8 MiB envelope. Schema 4 allows a 16 MiB envelope. Read, ReadNativeAssembly and native runtime loading accept it; older readers reject the required version. Small libraries keep schema 3. Schema-1/2 bounds remain unchanged. The native CBOR/semantic model is unchanged.

All other library limits remain: 32 MiB JSON, 2,097,152 nodes, depth 64, and 16 MiB total PE (MaxLibraryImageSize). Container/CLI overhead counts toward that PE limit. Exceeding any applicable bound throws InvalidDataException; no partial compiler artifact is published. No execution or complete bootstrap is implied by a successful write. Contracts and executable evidence.

Canonical native unit

TypeDefinition.SetNativePrimitive, TypeBuilder.SetNativePrimitive and AssemblyBuilder.SetNativePrimitive(ImportedTypeReference, PrimitiveType) accept PrimitiveType.Void for the explicitly selected canonical System.Void declaration. It represents NeoCLR's inhabited unit, usable in parameters, generic arguments and function results. There is no additional native Unit type.

Local declarations must be empty, nongeneric, top-level value types without constructors; wrong identities and storage reject through the existing validation. The external-reference API records host-supplied ownership without loading a consumer's dependencies. Native encoding records the scoped canonical unit alias; loading still requires its actual dependency. Manual definitions and builders share validation. Existing CLI executable primitive-provider rejection remains unchanged.

A signature using the designated declaration denotes a unit value; a bare PrimitiveType.Void return retains the API's CLI-compatible no-result convention. FunctionSignature.NoResult preserves that stack distinction across encoding and introspection. This is a low-level calling convention, not two Raven language types. Nominal CLI signature transport is retained where CLI void is illegal. The compiler owns target-specific lowering and supplies RuntimeUnitContract ownership; an arbitrary empty struct is never inferred to be unit.

External native Object authoring

AssemblyBuilder.SetNativeObjectRoot(ImportedTypeReference root) : void selects an output-owned nongeneric, nonnested reference named System.Object. Construct the reference with CreateTypeReference from the exact dependency identity/core/artifact digest, then select it before authoring signatures. Use AssemblyBuilder.ForDefinition(definition) for the same selection when manually constructing definitions. ObjectType returns that signature; CoreObjectType retains its explicit bootstrap identity.

The method rejects null/foreign/malformed references with argument exceptions and conflicting local/external selections with InvalidOperationException. Repeating the same selection is allowed. A caller supplies the host-validated root identity; this API does not load or inspect the dependency and does not substitute runtime admission. Unselected same-named identities do not satisfy Equals override validation.

Manual method definitions and builders share the exact Boolean Equals(selected Object) validation; ToString/GetHashCode retain their existing signatures. Authored/imported method references apply the same selected identity. Primitive-bootstrap Object type references and ELEMENT_TYPE_OBJECT signatures map to the selected root during import. Already-created signatures are not rewritten.

Native writing uses existing scoped module/type aliases for canonical System.Object, with no new format version. Reading checks the alias and exact Equals owner. The CLI reference image uses ELEMENT_TYPE_OBJECT; executable CLI output rejects a selected native root. Bootstrap-only behavior remains unchanged.

Validation and executable examples cover manual/builder parity, wrong owners, conflicts, native round trips and a Raven consumer against the source-built Runtime. These are host metadata APIs, documented here rather than in the guest RavenDoc reference assembly.

Imported erased Value representation

The existing AssemblyBuilder.SetNativePrimitive(reference, PrimitiveType.Value) selection now preserves the external carrier through native writing, reading and introspection. It writes the Value storage tag with a scoped System.Value alias and value-type reference, using the existing format. Competing explicit primitive owners reject. A same-named unselected type does not acquire this representation.

When importing the primitive bootstrap's empty nongeneric System.Value definition, an explicitly selected external carrier replaces that bootstrap reference. Retained service signature matching recognizes the same explicit Value designation without requiring a second seed-owned type. This does not replace System.Object or assign a .NET SpecialType to the carrier. Existing seed-owned and local-source cases remain supported; this adds no new public API or native instruction.

Executable evidence covers successful/error payloads through actual runtime services and canonical introspection parameter/return identity.

Imported Object slot references

AssemblyBuilder.CreateObjectSlotReference(string name, MethodSignature signature) returns an interned ImportedMethodReference for the explicitly selected external Object root. Supported contracts are String ToString(), Int32 GetHashCode() and Boolean Equals(ObjectType), without generic or out parameters. Call SetNativeObjectRoot(reference) first. No dependency is opened; the host provides identity and runtime linking validates the actual root and slot.

The returned contract has RequiresVirtualDispatch == true; use generator.Emit(OpCode.Callvirt, reference). Ordinary Call rejects with ArgumentException. This is an inherited slot declaration reference, not an override or interface method. Missing selection throws InvalidOperationException, invalid signatures throw ArgumentException, and conflicting ordinary/virtual references throw InvalidDataException. The reference retains its external assembly scope in CLI metadata and canonical native Object owner/name for runtime linking. No encoding category or version changes.

Body validation accepts reference-class receivers for the explicitly selected external root; values still require explicit boxing or constrained dispatch. Selection does not make arbitrary same-named types universal receivers.

C# and executable Raven validation covers slot interning/category, wrong signatures, incompatible contracts, wrong dispatch opcode and execution through a base-typed receiver. General imported virtual class methods remain outside this bounded API. Host API documentation lives here; it is not a new guest class-library API for the RavenDoc assembly snapshot.

Ordinary selected-root method references

CreateMethodReference on the explicitly selected external Object root uses the same canonical native owner/member names as authored root definitions. This includes nonvirtual GetType; it remains an ordinary instance call. Only CreateObjectSlotReference claims virtual-slot dispatch. Exact artifact identity and CLI member scopes are retained; no dependency is opened by authoring. A C# regression checks canonical names and ordinary-call classification, and the API fixture executes GetType against the actual source-built Runtime. This closes a JSON mapping link failure.

Native assembly-level Double constants

NeoCLR.Metadata.Experimental.Model.AssemblyConstantDefinition(string namespace, string name, double value, MethodVisibility visibility = Public) describes an assembly-level compile-time constant. Namespace and Name together form its qualified name; the containing assembly owns its identity. Read-only Namespace, Name, Value, Visibility properties return its exact declaration; AssemblyBuilder.AddConstant(definition) adds it, and ModuleDefinition.Constants reads authored/native snapshots. These host APIs are documented manually here, outside the guest RavenDoc selection.

Namespace/name are at most 1024 characters; namespace may be global/empty, otherwise its dot-separated segments and the simple name must be nonblank and control-free. Simple names contain no dot. Values must be finite Double, visibility Public or Internal. Invalid declarations and duplicate namespace/name pairs throw ArgumentException; null definitions throw ArgumentNullException. At most 4096 constants per assembly. Returned collections are read-only; loaded editing is absent. Values are inlined by the compiler, with no field address/storage or runtime initializer.

Native JSON/NEOX/PE retains exact 16-digit lowercase binary64 bit strings in assemblies[].constants, including negative zero. Native readers reject unsupported types, malformed bits, nonfinite values, unknown members and duplicates. Older readers reject the extension. Ordinary CLI reads expose no native constants; standalone CLI writing/projection explicitly rejects a graph containing them. The nonauthoritative CLI envelope accompanying a native PE does not project these constants; native readers must use #Neo. No native execution or guest reflection API is implied by this descriptive metadata. See Math contracts.

Terminology correction (2026-10-08): this unreleased API is now AssemblyConstantDefinition / AddConstant / Constants, and its manifest key is assemblies[].constants. Rebuild consumers and artifacts from the preceding same-day prototype; the former names/key are not compatibility aliases. Namespace remains part of the member name. Types and functions can also be assembly-level members; see the naming contract.

Assembly-level member model

Model.AssemblyDefinition.GetMembers() : IReadOnlyList<AssemblyMemberDefinition> provides one read-only view over authored graphs and loaded metadata. The writer's AssemblyBuilder.Definition exposes the same API as the reader's returned definition. The view has no new identity separate from its underlying declaration.

AssemblyMemberKind has Type, Function and Constant cases. Each AssemblyMemberDefinition exposes Kind, Module, Assembly, Namespace, Name and FullName, and exactly one non-null typed property: Type (TypeDefinition), Function (MethodDefinition) or Constant (AssemblyConstantDefinition). FullName includes the namespace, but excludes assembly identity and overload signatures. Resolve a member using its assembly identity and declaration contract as well as its qualified name.

Introspection.AssemblyInfo.GetMembers() : IReadOnlyList<AssemblyMemberInfo> provides the corresponding reader facade. AssemblyMemberInfo exposes Kind, Assembly (AssemblyInfo), Module (ModuleInfo), Namespace, Name, FullName, and lazily obtained Type (NominalTypeInfo?) / Function (MethodInfo?) views. ConstantValue (double?) returns the current finite-Double constant value, or null for another member kind. Type/function view resolution uses the supplied MetadataLoadContext and its existing resolution errors; no CLR assembly loading or guest invocation occurs.

Both lists include public and internal assembly-level declarations, in type/function/ constant groups with declaration order retained within each group. Nested types, type-owned methods/fields and the CLI Module pseudo-type are excluded. Existing typed collections remain available for those relationships. Lists are fresh/read-only; underlying authored graphs keep their existing append-only behavior. Single-manifest- module support remains the present limit. Ordinary CLI input retains its physical declarations; the API does not reinterpret a compiler-generated carrier as native members.

AssemblyConstantDefinition also exposes FullName, Module? and Assembly?. A newly constructed constant is unattached. AddConstant attaches it once; reusing that instance in another graph throws InvalidOperationException without modifying either graph. Loaded constants are already attached to their module and assembly. Native round trips preserve that ownership, member kinds, qualified names and overload signatures. Equal qualified names in different assemblies retain different owners.

Compared with .NET Assembly.GetTypes and Module.GetMethods, this facade offers one assembly-level declaration view across types, functions and constants. Unlike GetTypes, the new GetMembers view excludes nested types because they keep a declaring-type owner. This makes ownership explicit to metadata tools; the cost is an additional view object per enumerated member and a bounded single-module implementation. No performance or complete CLR-reflection compatibility claim is made.

Self-owned native core emission

AssemblyBuilder(identity, coreLibrary) may use the same identity for both when emitting a native PE/#Neo reference container through the builder overloads of RuntimeAssemblyContainer.WriteBinary or WriteLibraryBinary. Author an explicit AddNativeObjectRoot() and the core declarations required by the projection: System.ValueType for value types, System.Enum for enums, and System.Runtime.CompilerServices.ReferenceAssemblyAttribute for its reference marker. Callable carriers and Self signatures require their corresponding local declarations when used. The marker's parameterless constructor and valid base chain should be provided as in the tested producer.

Physical core references use local TypeDef handles, not an AssemblyRef to the output. Missing referenced local declarations or an absent native Object root raise InvalidDataException. Write() remains unsupported for this native core profile; ordinary external-core emission retains its existing contract. General foreign references colliding with output identity still reject. This is producer support, not a complete core profile validator, compiler bootstrap or executable CLI core. Raven's opt-in compiler API native-only consumer now emits and executes integer arithmetic; full source-library/core qualification remains pending. See the frontier and validation.

Native-only project selection

NeoClrProjectMetadataProvider.Load accepts the project-relative RavenNeoClrNativeCoreReference property, mutually exclusive with the legacy RavenNeoClrCoreReference. With NeoCLR target/metadata format, it returns only native references and configures native core Object/unit ownership. GetInputPaths includes that core for watching. The resulting configuration's ReferencePaths includes the core, ObjectRootPath selects it, and CreateEmissionBackend consumes the native catalog without a CLI bootstrap.

An optional RavenNeoClrRuntimeSeed must exist and differ from semantic inputs; it is execution-only. Mixed bootstrap ownership/intrinsic/source-root/object-library/ async-library settings and mismatched core identity reject with InvalidDataException. Missing native inputs retain the catalog's I/O errors. Failed loading does not replace the last successful configuration. This bounded path does not establish full core completeness or installed-editor qualification. See the executable project check.

Native erased-result operands

IILGenerator.Emit(OpCode.ValueIs, SignatureType) consumes an erased Value and produces Boolean. ValueUnpack consumes Value and produces the operand type; a mismatched tag raises RuntimeError. Method generic parameters are supported. Void, managed references, pointers and Self operands are rejected. These are neoCLR storage operations, distinct from CLR object isinst and unbox.any; they do not allocate a box. Executable CLI output rejects these operations; reference-only CLI projections carry signatures, not executable behavior.

Validation: NeoCLR.Metadata.Experimental.Tests --erased-values <directory> writes matching/mismatched slice consumers and checks round-trip, operand/stack rejection and CLI rejection. The interpreter returns 42 for the matching consumer and a RuntimeError with a managed stack for mismatched extraction.

Primitive bootstrap references

TypeDefinition.IsNativePrimitiveReference identifies a memberless storage reference. TypeDefinition.SetNativePrimitiveReference(PrimitiveType) and the corresponding TypeBuilder method designate it. The canonical System identity, primitive category and ordinary native primitive restrictions still apply. Methods, properties and interfaces are forbidden; invalid authored declarations throw ArgumentException, and loaded definitions remain immutable.

Native metadata writes primitive_reference: true and both definition readers preserve it. The runtime load set must supply exactly one executable declaration of that primitive. Missing or competing implementations fault during loading; references cannot be executed on their own. This is an explicit bootstrap contract, not an ordering rule for shadowing duplicate types. Executable CLI emission rejects native primitive declarations as before. Char retains its separate grapheme contract and is not admitted by this API.

For example, a native core catalog can reference String storage while the separate production String library supplies the implementation. This differs from CLR core library identity resolution: neoCLR explicitly separates the bootstrap storage reference from its executable owner. The benefit is native-only source bootstrap; the cost is an additional load-set validation rule. It does not grant arbitrary cross-assembly primitive replacement or promise a stable native ABI.

Init accessors

PropertyDefinition(name, propertyType, getter = null, setter = null, isInitOnly = false) and TypeBuilder.AddProperty(name, type, getter = null, setter = null, isInitOnly = false) accept a trailing initialization-only flag. True requires an instance setter and retains normal signature, ownership, duplicate-association and index checks; missing or static setters throw ArgumentException. The default preserves ordinary setters.

PropertyDefinition.IsInitOnly and metadata Introspection.PropertyInfo.IsInitOnly are immutable Boolean queries. They survive native JSON/binary reading and generic property projection. CLI property reading recognizes the standard required return modifier; CLI transport/reference writing and imported calls preserve it. Native metadata uses its own init_only field, with no CLI PropertyAttributes bit reuse.

Only the declaring constructor or associated init setter may write the type's readonly fields. Ordinary method calls, including reflection calls after construction, remain executable. The flag is a compiler usage contract, not a runtime freeze. This metadata-tooling API is distinct from the Raven runtime PropertyInfo surface; no new query or invocation restriction is added there. See the design and validation.

Member custom attributes (development 2026-10-10)

The host .NET metadata library extends existing type attributes to methods (including constructors and assembly-level functions), fields, properties and parameters. These are host authoring/introspection APIs, not guest System.Introspection changes.

API Contract
MethodDefinition.CustomAttributes, FieldDefinition.CustomAttributes, PropertyDefinition.CustomAttributes IList<CustomAttributeDefinition> of declared annotations. Authored lists accept output-module-owned attributes; loaded lists are read-only. Maximum 256 per declaration.
MethodBuilder.AddCustomAttribute(CustomAttributeDefinition attribute) Convenience method using the definition's ownership checks. Foreign-module attributes throw ArgumentException.
MethodDefinition.GetParameterCustomAttributes(int position) Attribute list for a zero-based declared parameter, excluding a receiver. Invalid positions throw ArgumentOutOfRangeException; unsupported signatures throw NotSupportedException. Same ownership, count and read-only rules.
Introspection.MethodInfo.GetCustomAttributes(), FieldInfo.GetCustomAttributes(), PropertyInfo.GetCustomAttributes(), ParameterInfo.GetCustomAttributes() IReadOnlyList<CustomAttributeInfo> of declared data. No constructors, getters, test bodies or runtime code execute. Attribute type resolution requires an explicit metadata catalog. No inherited search.

Example: method.AddCustomAttribute(new CustomAttributeDefinition(markerConstructor.Definition, [])); field.Definition.CustomAttributes.Add(attribute) and method.Definition.GetParameterCustomAttributes(0).Add(attribute) use the same data contract. Attribute constructors need not be executable to inspect stored data.

CLI, native PE/#Neo and NEOX snapshots and native-to-CLI reference projection preserve supported attributes. Fields/properties use validated enclosing-type target tokens; parameters use enclosing-function parameter tokens. An absent target annotates the enclosing declaration. Malformed or foreign targets fail with InvalidDataException. ParamArrayAttribute remains inspectable alongside ordinary parameter attributes and its IsParameterArray policy; projection avoids synthesizing it twice.

Payload authoring remains bounded to String, Int32 and Boolean fixed arguments on supported nongeneric nominal constructors. Enum/named arguments and AttributeUsage policy are pending. Native literal-field annotations are explicitly rejected pending literal metadata-token support. Assembly/module, return-value and generic-parameter annotations are not added by this slice. Rewriting loaded snapshots remains unsupported. Earlier bounded host readers may reject newly admitted data; use matching tools.

Design, scope and validation. No guest reference assembly or RavenDoc type selection changes are required for this host-only API; this manual reference supplies the signatures and limitations.

Enum and named attribute data (development 2026-10-10)

Host-only, NeoCLR.Metadata.Experimental.Model; this does not extend the guest System.Introspection descriptor yet.

API Contract
CustomAttributeArgument(SignatureType type, object? value) Immutable Type : SignatureType and Value : object?. Supports String/null, Int32, Boolean and nominal Int32-backed enum identities with an Int32 storage value. Invalid combinations throw ArgumentException. Owned enum identity is retained; external identities require validation against linked dependencies.
CustomAttributeNamedArgument(string name, bool isField, CustomAttributeArgument value) Immutable MemberName : string, IsField : bool, TypedValue : CustomAttributeArgument. String/Int32/Boolean values only in this slice. Invalid/empty/control-containing names, names over 1,024 characters or unsupported types throw ArgumentException.
CustomAttributeDefinition(..., IEnumerable<CustomAttributeNamedArgument>? namedArguments = null) All three constructor overloads accept optional named arguments, copied into read-only storage. At most 256 per group; duplicate named members reject. Local member access/kind/type checks run on output; explicit external references are checked when linked. No assignments execute.
CustomAttributeDefinition.GetNamedArguments() Returns IReadOnlyList<CustomAttributeNamedArgument>, declared order, without invoking user code. Malformed data throws InvalidDataException; unsupported categories throw NotSupportedException.
Introspection.CustomAttributeInfo.GetNamedArguments() Same immutable metadata-only named data through the host inspection view.
CustomAttributeDefinition.GetConstructorSignature() Copies a loaded signature or a primitive-only authored signature. Authored enum signatures require output token assignment and throw NotSupportedException here; use GetArguments for logical types. CLI writing assigns tokens and emits the complete signature.

Migration: Type was PrimitiveType and is now SignatureType. Existing PrimitiveType constructor arguments convert implicitly; consumers inspecting Type should inspect its Primitive property or nominal identity. Enum values retain their Int32 storage value; the associated Type carries their semantic identity. GetValue includes the CLI named entries. Previously supported marker/scalar call sites remain valid.

var data = new CustomAttributeDefinition(usageConstructor.Definition,
    [new(attributeTargetsEnum, 64)],
    [new("AllowMultiple", false, new(PrimitiveType.Boolean, true)),
     new("Inherited", false, new(PrimitiveType.Boolean, false))]);
attributeType.AddCustomAttribute(data);

This assumes output-owned declarations for the enum, constructor and public writable Boolean properties. It records data; it does not establish AttributeUsage enforcement. Named inherited members, named enums, arrays, System.Type and wider primitives are not supported. The CLI decoder currently handles the Int32 enum storage profile; it is not a general-purpose decoder for arbitrary external enum backing types. Native named-data records require matching metadata/runtime readers. Guest inspection currently rejects named data explicitly; it never silently drops it.

Scoped external class-base readers (development 2026-10-10)

TypeDefinition.BaseType now retains a nongeneric top-level external base as an assembly-scoped TypeReference when the native manifest supplies an explicit matching native type/module binding. NominalTypeInfo.BaseType resolves that reference through the existing fixed MetadataLoadContext catalog, returning its canonical parent view. Missing dependencies and wrong versions throw InvalidDataException; no file probing, name-only fallback or code execution occurs. Snapshot Write preserves the original container and relationship.

This follows .NET's scoped base-type identity, while keeping metadata loading separate from execution. The reader admits ordinary top-level nongeneric class owners and rejects unbound, value, nested or generic base bindings. The dependency's actual class category, visibility, sealed state and cross-assembly cycle/constructor/layout legality still require semantic/link verification; descriptive loading does not establish them. Output-side external inheritance and constructor chaining remain unsupported. CLI reference projection continues to reject inheritance instead of dropping the base. The focused local/external reader gate covers identity, missing/wrong-version resolution, canonical views, copies and malformed bindings across schema-2/3 NEOX snapshots.

Fieldless external class-base authoring (development 2026-10-10)

AssemblyBuilder.DeclareFieldlessClassBase(ImportedTypeReference type) records an explicit compiler-host contract: a public, nonsealed, nongeneric, top-level class hierarchy without instance storage, interfaces or additional virtual slots. The host must validate dependency facts; this API checks reference ownership/shape, not dependency layout. It does not load files. Foreign, value, interface, nested or generic references throw ArgumentException.

AssemblyBuilder.AddClass(string namespace, string name, ImportedTypeReference baseType, TypeVisibility visibility = Public) requires that contract and creates an owned derived class. Undeclared bases/invalid visibility throw ArgumentException. The existing local-base overload is unchanged. CLI extends and native base bindings retain the exact dependency identity. Linking still validates actual declarations.

CreateMethodReference gains optional MethodVisibility visibility = Public. Only a nonstatic .ctor may additionally use Protected; other nonpublic imports remain unsupported. Imported protected constructors can be called by the direct derived constructor with its uninitialized receiver. Allocation through newobj, missing initialization and double initialization fail validation. This follows CLR constructor access/initialization semantics within a narrower supported hierarchy. No general external field-layout or inherited virtual-dispatch support is claimed.

Validation: NeoCLR.Metadata.Experimental.Tests --external-class-base <output> checks metadata, actual CLR execution and negative constructor cases. Its native artifact returns 42 in the interpreter. A Raven TestAttribute : Attribute sample also returns 42 in interpreter and macOS ARM64 AOT with the matched compiler.

External class storage and virtual slots (development 2026-10-10)

The fieldless contract above remains available. The new host-only AssemblyBuilder.CompleteClassBaseReference(ImportedTypeReference type, IEnumerable<ImportedMethodReference> methods, int declaredInstanceFieldCount) additionally admits ordinary nongeneric, top-level reference bases with dependency-owned instance storage, interfaces and virtual methods. Supply every declared public instance method and property accessor, excluding constructors, plus direct base/interface edges. Supply the own instance storage count (including private fields, 0–256); derived native field ordinals include all external ancestor counts. Invalid counts throw ArgumentOutOfRangeException. Missing ancestor layout contracts fail emission with InvalidDataException. Null arguments throw ArgumentNullException; foreign, duplicate, unsupported or conflicting contracts throw ArgumentException. The compiler supplies resolved facts; this API does not load or copy dependency fields.

CreateMethodReference adds optional bool isVirtual = false and bool isAbstract = false. Class slots require nongeneric instance signatures; abstract slots require virtual and cannot also be overrides. isOverride reuses an inherited slot. Conflicting repeated contracts throw InvalidDataException. Interface contracts keep their existing implicit abstract/virtual behavior. Protected visibility remains constructor-only; protected ordinary methods and generic bases are still gaps.

DeclareClassBase now permits edges across explicitly registered dependency assemblies. Identity, ownership, cycle and conflicting-base checks remain. AddClass accepts either a fieldless declaration or a completed class contract. Overrides must match inherited virtual signatures, and concrete classes must implement inherited abstract members. Inherited interface contracts participate in conversions and implementation validation. An imported public concrete virtual member permits direct Call, including calls from a synthesized async state machine; normal dispatch uses Callvirt. Receiver assignability is still checked. Source-language base access remains a compiler check. Standalone metadata cannot resolve an external override: linking validates it against the actual dependency definition.

This follows CLR storage ownership, slot reuse and direct base-call semantics, within the stated nongeneric/public-member subset. The focused --external-class-base regression executes a field-bearing abstract base and concrete override on the CLR, returns 42, and rejects a missing abstract implementation and conflicting layout counts. A derived field has native ordinal 1 after the base’s private field, and CLR execution observes both independently. Guest native qualification is recorded with the HTTP pipeline consumer when complete.

Assembly custom attributes (development 2026-10-10)

Host-only NeoCLR.Metadata.Experimental.Model; these are physical assembly annotations, not logical namespace/module annotations or guest reflection APIs.

Member Contract
AssemblyDefinition.CustomAttributes : IList<CustomAttributeDefinition> Declared assembly attributes. Authored lists accept up to 256 output-module-owned attributes; loaded lists are read-only. Reading never executes constructors.
AssemblyBuilder.AddCustomAttribute(CustomAttributeDefinition attribute) : void Appends through the definition's ownership validation. Foreign ownership throws ArgumentException; exceeding 256 attributes throws InvalidDataException.

AssemblyBuilder.Write() emits these attributes on the CLI assembly manifest. AssemblyDefinition.ReadAssembly() retains ordered repeated attributes and shares the existing bounded attribute-blob decoding budget with member attributes. Primitive, nominal enum and named argument restrictions match CustomAttributeDefinition. Unsupported argument data can be retained raw but still rejects typed decoding. Loaded snapshots remain immutable and Write() preserves their original bytes.

For example, author a friend grant with a module-owned reference:

var marker = assembly.Definition.MainModule.ImportReference(coreIdentity,
    "System.Runtime.CompilerServices", "InternalsVisibleToAttribute");
assembly.AddCustomAttribute(new CustomAttributeDefinition(marker,
    [new CustomAttributeArgument(PrimitiveType.String, "Library.Tests")]));

This API retains metadata; the authoring library does not perform general AttributeUsage validation. neoCLR resolved runtime access now recognizes unsigned simple-ASCII friend grants, and Raven imports friend-approved internal symbols. Complete identity support and Windows qualification remain pending; the native friend consumer passes macOS ARM64 AOT execution. Native writing now records assemblies[].custom_attributes using the existing constructor/fixed/named argument schema. Native JSON, PE/#Neo and standalone NEOX readback, and native-to-CLI reference projection, preserve ordered assembly annotations. The native reader rejects member target tokens and more than 256 annotations per assembly. Existing native member attribute support is unchanged. CLI reference emission uses the same assembly writer. Native signed dependency import remains restricted; retaining a friend string containing a public key does not implement full-key native assembly identity or grant access.

Host assembly annotation views and CLI property decoding

NeoCLR.Metadata.Experimental.Introspection.AssemblyInfo.GetCustomAttributes() returns IReadOnlyList<CustomAttributeInfo> containing declared assembly annotations, cached per assembly view. The list is read-only; metadata inspection never invokes constructors or named assignments. GetAttributeType() resolves through the context's explicit catalog and reports missing/mismatched types with InvalidDataException, as other annotation views do. This is a host API; no guest AssemblyInfo method is introduced.

PropertyDefinition.TryGetSignature now accepts bounded non-indexed CLI nominal results through the existing method-signature decoder, preserving enum/type identity without loading code. This supports enum-valued AttributeUsage.ValidOn. Indexed CLI properties remain outside this reader profile; native/authored indexers remain supported. CLI void results, unsupported encodings and malformed blobs return false. Primitive-only callers can continue using TryGetPrimitiveSignature.

Native value-field reads

CreateFieldReference and ImportReference(FieldDefinition, ...) now admit native value-type owners. LoadField validates exact owner identity after generic substitution; managed local/parameter receivers must be initialized. Wrong receivers and uninitialized loads fail body validation with InvalidDataException. StoreField on an external value owner fails validation even for non-readonly storage. Public API signatures and native field-slot encoding are unchanged. This supports Tuple<int,int>.Item1/Item2 used by range resolution. Focused authored-reference checks and the Raven array suite qualify both model validation and interpreter/AOT execution. No new field-address API is added.

Nested generic lexical owners

TypeBuilder.AddNestedGenericClass(string name, IEnumerable<string> parameters, TypeVisibility visibility = TypeVisibility.Public): TypeBuilder creates a nested reference class. The name is simple, without an arity suffix; parameters are copied, unique names, one through 32. Public and Internal map to CLI NestedPublic and NestedAssembly. No constructor is synthesized. Invalid names, duplicates, visibility, ownership or limits throw ArgumentException; null parameters throw ArgumentNullException.

All nested class/value builders and TypeDefinition.NestedTypes now accept generic enclosing definitions. Each definition owns its complete generic parameter list: a compiler redeclares the enclosing parameters first, followed by new parameters, and supplies the complete list at construction. Ownership does not itself inject parameters or an enclosing object instance. As with the existing host builder, generated names encode the complete arity; this is a naming convention rather than a different runtime generic scope. Standard CLI NestedClass/GenericParam/TypeSpec tables represent the same ownership and construction. The .NET execution fixture reads a private enclosing field through a nested generic method.

Public nested imports retain the enclosing definition's arity, without constructing that definition. Native binary round-tripping, reference projection and translated library bindings preserve this scope. Translated native_type_bindings optionally carry declaring_arity (0 when omitted), disambiguating enclosing definitions with the same translated name. The value is bounded to 32 and requires a declaring name. The direct native encoded identity already contains enclosing metadata names/arity. Private/internal imported enclosing scopes remain rejected.

Validation: dotnet run --project tools/metadata/NeoCLR.Metadata.Experimental.Tests -- --generic-nested-types covers CLR execution, native and external round-trips, reference projection, translated bindings, three-level generic nesting and rejection of implicit enclosing parameter use. The existing --nested-type-integration consumer remains valid. This host-only API follows the documented RavenDoc exclusion; no guest API or reference assembly changes.

Nested classes with a source-owned Object root

TypeBuilder.AddNestedClass(string name, TypeBuilder baseType, IEnumerable<string>? parameters = null, TypeVisibility visibility = Public) creates a nested reference class whose direct base is the same assembly's explicit native Object root. Null parameters mean nongeneric; otherwise supply the complete nested generic scope. Ordinary or foreign bases are rejected before attachment. Constructors must initialize that direct base. Native authoring, serialization, loading and introspection preserve both lexical ownership and base identity.

This fills a metadata gap exposed when the runtime library itself contains async methods: their nested generated state machines have the same Object base as other source-defined classes. CLI metadata already represents nested ownership and class inheritance independently; this adds no new wire-format concept. General nested inheritance remains outside the bounded authoring surface. Validate with the metadata test executable's --generic-object-roots group.

Native imports

NativeImportDefinition(library, entryPoint, stringMarshalling = null, callingConvention = "Cdecl", parameterMarshalling = null, returnMarshalling = null, callbackParameters = null, functionReturn = null) records an immutable foreign ABI descriptor. Library/EntryPoint must be nonempty and NUL-free; conventions are Cdecl/System; string defaults are Utf8/Utf16; per-slot values are Utf8/Utf16/Bool8/Bool32. Parameter indices are zero-based and copied on construction. Invalid option values throw ArgumentException. No library is loaded.

Development (2026-10-22): NativeCallbackDefinition(string callingConvention = "Cdecl") records a scalar callable ABI. Callback parameters are synchronous, same-thread and call-scoped. Its read-only CallingConvention: string accepts Cdecl or System; other values throw ArgumentException. NativeImportDefinition.CallbackParameters exposes a defensively copied, read-only IReadOnlyDictionary<int, NativeCallbackDefinition> supplied through the constructor's optional callbackParameters argument. Negative indices or null entries throw ArgumentException; out-of-range indices, conflicting per-parameter marshalling and unsupported Function shapes throw InvalidDataException when attached. Numeric scalar parameters with numeric or no-result returns are supported. Boolean, String, pointer, nested Function and nominal value-returning Void slots are rejected. The binary/JSON reader preserves these descriptors and rejects richer callback ABI records outside this bounded subset. Raven handles logical unit returns through an adapter; the SDK does not silently erase a value-returning signature. Native code must not retain the callback or call it on another thread. This host API is documented here rather than in RavenDoc's guest-library type selection.

NativeImportDefinition.FunctionReturn: NativeCallbackDefinition? exposes the optional constructor functionReturn descriptor for a returned native function pointer. The method result must be a supported structural Function shape; scalar/missing/incompatible shapes or simultaneous return marshalling throw InvalidDataException on attachment. JSON/binary preserve function_return. The interpreter rejects null/data addresses and retains loaded library owners through the returned Function. It does not take ownership of foreign state. Raven projects (int) -> unit results through an adapter that invokes the C no-result function and materializes logical System.Void. The returned adapter allocates once per import result, rather than on each invocation. This is distinct from callback-parameter adapters, which are scoped to each call.

MethodDefinition.NativeImport exposes the descriptor after authoring or native reading. Introspection.MethodInfo.NativeImport: NativeImportDefinition? exposes that immutable descriptor through a loaded callable view, or null for a method without a native import. Library/entry point, calling convention, default encoding and parameter/result overrides are preserved. Reading this property does not load a native library, resolve an export, invoke native code or synthesize custom attributes. Reference-only CLI stubs do not carry the descriptor; inspect the native artifact for authoritative information. MethodDefinition.SetNativeImport and MethodBuilder.SetNativeImport require an empty nongeneric static declaration with no implementation flags, abstract/virtual slot or generic owner. Invalid declaration state throws InvalidOperationException; unsupported signature/marshalling combinations throw InvalidDataException. Graph validation rechecks later mutations, including an import used as the entry point. SetInternalCall rejects an already imported declaration. Native JSON/binary preserve all descriptors; executable CLI writing rejects imports while reference projections retain throwing stubs. See the runtime contract.

Introspection.MethodInfo.GetMethodImplementationFlags(): System.Reflection.MethodImplAttributes returns recorded implementation bits without loading code. Native snapshots currently admit zero, NoInlining, AggressiveInlining, their combination, or InternalCall; CLI snapshots expose their recorded bits without promising native execution support. InternalCall identifies a runtime service and has no NativeImport descriptor. Foreign imports have a descriptor and zero implementation flags; ordinary native managed methods may carry inlining hints. This follows .NET's inspection API without treating Unmanaged, Native or other flags as implemented neoCLR features. Abstract methods must still be identified through IsAbstract; the absence of a foreign descriptor does not imply an executable managed body.

Read-only reference compositions (experiment, 2026-10-14)

Unpublished, on codex/structural-union-intersection. These .NET host APIs are in NeoCLR.Metadata.Experimental.Model; they are not guest reflection types and do not change the generated RavenDoc snapshot.

API Contract
AssemblyDefinition.ReadNativeAssembly(ReadOnlySpan<byte> image, bool allowExperimentalCompositions) Copies a PE/#Neo or standalone NEOX image into an immutable native declaration snapshot. true explicitly admits the subset below; false and the existing one-argument overload reject compositions. Invalid/unsupported declarations or exceeded bounds throw InvalidDataException.
SignatureType.Composition : ReferenceCompositionSignature? The read-only compound descriptor, or null for other signatures and normalized singleton results. No public compound factory is provided.
ReferenceCompositionSignature.Kind : ReferenceCompositionKind Union means either-membership; Intersection means all-membership. These compose nominal contracts, not matching member names.
ReferenceCompositionSignature.Constituents : IReadOnlyList<SignatureType> Immutable normalized bounds, in first-occurrence order, retaining snapshot-owned nominal references. Same-kind nesting is flattened, equal bounds are deduplicated and singletons collapse. Mixed nesting remains. Nominal subtype reduction is deliberately absent.
ReferenceCompositionSignature.Equals(ReferenceCompositionSignature? other), Equals(object? obj), GetHashCode() Equality/hashing ignore constituent order and retain nominal scope/ownership through existing signature identities. Different kinds remain distinct; null compares unequal. This is snapshot signature identity, not a cross-catalog canonical identity API.
ReferenceCompositionSignature.ToString() Diagnostic kind/bound display; not an encoding, parser contract or stable identity.

Only nongeneric, non-native free-function parameter/result signatures and local signature declarations admit compositions. Each encoded compound has 2–256 operands, at most 4,096 nodes per root and a depth limit of 32; existing transport limits also apply and may reject an image earlier. Leaves must be closed nominal reference classes/interfaces, including constructed generic types. Generic arguments may be closed nominal/value types, non-Void primitives or vectors; arity and existing nominal construction validation apply. Open arguments reject. Closed local unconstrained reference-class wrappers may contain composition arguments in the opt-in free-function profile; ordinary builder construction still rejects them. Primitive/value, array, byref, generic parameter, Function and Self leaves are rejected, as are compositions nested inside arrays, byrefs or function shapes, explicit fields, owned methods and native/InternalCall signatures. Validation precedes normalization, so collapsing duplicate bounds cannot hide an invalid leaf. External leaves retain the reader's existing declared dependency identity rules; this slice does not resolve external assemblies or prove runtime inhabitation.

The descriptor is immutable: builder ownership validation and ordinary callable import reject it explicitly. The separate experimental callable-import API below admits a bounded native-only path. CLI projection of compound declarations remains rejected. AssemblyDefinition.Write() copies the original image byte-for-byte; it does not regenerate declarations or validate executable bodies. The native reader still treats bodies as opaque, and this API is not a runtime verifier.

.NET/CLI has no equivalent first-class union/intersection signature. Reading the native shape preserves constituent information without inventing a carrier ABI; the cost is an explicit boundary before compiler import, authored storage and code generation. Raven's default adapter still rejects compound declarations. Its separate experimental intersection API now supports semantic inspection while rejecting structural unions and keeping native emission gated by default. An explicit host option now admits native-only forwarding between imported intersection calls. See the experiment record for validation, remaining identity differences and the next compiler slice.

The NeoCLR.Metadata.Experimental.Introspection facade exposes these loaded signatures through MetadataLoadContext.ResolveSignature and function result/ parameter discovery. It performs catalog resolution without loading or executing assemblies. Missing dependencies or foreign snapshots throw InvalidDataException. The reader opt-in remains the admission boundary; no second switch is needed to inspect an already admitted immutable snapshot.

API Contract
ReferenceCompositionTypeInfo : TypeInfo Context-owned, read-only view; no public constructor. Reference equality is canonical within one context, including reordered bounds. Separate contexts remain distinct.
ReferenceCompositionTypeInfo.Kind : ReferenceCompositionKind Preserves union versus intersection, including mixed nesting.
ReferenceCompositionTypeInfo.Constituents : IReadOnlyList<TypeInfo> Immutable canonical nominal/composition bounds, in the first projected signature's order. Resolved duplicate bounds collapse; a singleton resolves directly to its constituent view. No nominal subtype reduction or distributive rewriting.
ReferenceCompositionTypeInfo.DisplayName : string Diagnostic kind/bound display; not a binding identity or stable serialization.
ReferenceCompositionTypeInfo.IsNominalType : bool Always false; the composition does not invent a nominal declaration.

Composition projection retains the reader's depth limit of 32. It adds no assignability, synthesized members, callable import or code generation. Existing non-composition projection limits remain unchanged. Raven's explicit experimental API now maps intersection views to semantic symbols; structural union import and native emission remain pending.

Experimental composition callable import (2026-10-14)

AssemblyBuilder.ImportExperimentalCompositionReference(MethodDefinition definition, AssemblyIdentity dependencyCoreLibrary, IAssemblyResolver? resolver = null) returns an output-owned ImportedMethodReference for a nongeneric native free function. The definition must come from an immutable native snapshot; compositions require the reader opt-in above. Owned methods, generic functions and native/InternalCall implementations are rejected. Null definition/core arguments throw ArgumentNullException; unsupported declarations, incompatible core identities, missing/mismatched dependencies and normal import limits throw InvalidDataException. The optional resolver supplies exact nominal dependencies without implicit loading.

Intersection bounds must be resolved interfaces or reference classes that permit subclassing. CLR-final classes reject before normalization, including duplicate/singleton reduction. Raven sealed hierarchies (closed families with permitted subtypes) remain admissible; these are distinct from classes closed to extension. Value types remain excluded. Sealed union alternatives remain supported. The bounded reader rejects external intersection bounds whose extendability it cannot establish; resolving those dependencies during reading remains a gap. This narrows the unpublished experimental profile following the author's 2026-10-14 clarification.

The returned Signature preserves union/intersection kind and all normalized native bounds, imported into the output builder's identity scope. Same-kind flattening/deduplication remains unchanged; nominal-supertype reduction is not performed. Repeated imports reuse the callable. Ordinary ImportReference still rejects a compound contract, even after its experimental import has been cached. No new public compound signature factory or authored storage capability is added.

The native writer serializes compound call operands with their imported nominal identities. Body validation retains the descriptor as a stack type: exact compound results can feed equivalent compound parameters, including reordered bounds. For call arguments only, flat nominal-reference compositions admit a bounded proof. A nominal bound implies another through identical scoped identity or its declared interface graph. The four composition cases are:

Source Target Required proof
Union Union Every source alternative implies some target alternative.
Union Intersection Every source alternative implies every target bound.
Intersection Union Some guaranteed source bound implies some target alternative.
Intersection Intersection Every target bound follows from some guaranteed source bound.

Thus A & Both can feed B & Both or A & B when Both implements both interfaces. Both | OtherBoth can feed A & B when both classes implement A and B. Merely matching the bounds of A | B and A & B is insufficient. Proof uses declared contracts, never the concrete allocation inside a producer body. Original composition kinds and bounds remain in emitted call descriptors.

This adds no nominal/compound injection/projection, class-base traversal, nested mixed-composition proof, storage or boxing conversion.

AssemblyBuilder.Write() and its reference-image path reject graphs containing compound callable imports with InvalidDataException. Compound declarations also remain unsupported by CLI projection. A native caller whose declarations have no compounds may still be packaged by existing transports; its native body remains subject to runtime feature gates and verification. Authored locals, fields, parameters/results and wrapper types continue to fail ownership validation. Runtime interpretation requires experimental-compositions; JIT/AOT remain closed.

Focused checks and three emitted native callers cover union, intersection and redundant A & Both bounds (Both implements A): all return 42 in the interpreter. This is host metadata API emission, not Raven source emission. Raven's experimental importer retains its default NEOMETA001 guard. The explicit AllowExperimentalIntersectionCalls host option now preserves these original descriptors through lowering and native call encoding; it does not enable general storage or PE/CLI projection. See the experiment record for compiler validation.

Companion compiler composition POC APIs (2026-10-14 development)

Raven's separate native compiler assembly now exposes NeoClrMetadataReference.ReadExperimentalCompositionAssembly(image, bootstrap) and NeoClrEmitOptions(..., allowExperimentalCompositionCalls: true). The reader admits flat union/intersection free-function signatures; the option permits native call forwarding, preserving raw descriptors. Old/default readers and the narrower intersection-only option remain closed to unions. PE/CLI and authored storage remain unsupported. Rebuild compiler hosts for the new optional constructor parameter. Invalid native signatures/mixed nesting reject with InvalidDataException; unsupported emission reports diagnostics without output.

Semantic APIs are Compilation.CreateStructuralUnionTypeSymbol(params ITypeSymbol[]), IStructuralUnionTypeSymbol.ConstituentTypes, TypeKind.StructuralUnion and SymbolVisitor.VisitStructuralUnionType (including the generic visitor). The factory flattens/deduplicates same-kind unions, collapses singletons and preserves presentation order, with order-independent identity/hash and no nominal carrier. Empty/unsupported input throws ArgumentException; null input/elements throw ArgumentNullException. Nominal types (including value types and open/closed constructions) and bound type parameters are supported semantically. Unbound generic placeholders and Void are rejected. Owner/method substitution traverses union alternatives and generic arguments, deduplicating after substitution. IsReferenceType/IsValueType require all alternatives to have that category; neither selects a storage representation. Written intersection bounds now reject sealed classes/value types before reduction. Member merging is deferred. These are compiler host APIs, not guest RavenDoc APIs.

POC and commands record four interpreter results and negative gates. Full open/closed generic native integration remains incomplete; the adapter admits closed generic reference bounds in nongeneric free-function calls. Open parameters remain unsupported. Closed reference-class wrappers now retain composition arguments in the imported free-function call profile. The runtime separately supports closed generic reference bounds; see the generic slice.

Closed generic bound call integration is covered by eight Raven interpreter consumers and host/compiler mismatch rejection; see the current profile and evidence.

The wrapper profile retains invariant argument identity and recursively enforces native-only emission and ordinary-import/storage rejection. It requires local unconstrained reference-class definitions; value/interface wrappers and compositions inside a composition bound's generic arguments remain outside this reader profile. Wrapped composition contracts and validation.

Imported composition result locals (2026-10-14 development)

public LocalDefinition MethodBuilder.DeclareExperimentalCompositionResultLocal(
    ImportedMethodReference producer);

Declares a local with exactly producer.Signature.ReturnType, including a closed reference wrapper containing union/intersection arguments. The producer must belong to the current output assembly and have been imported through the experimental native composition callable profile. Its result must contain a composition; an ordinary scalar result is rejected. The declaring body must be a nongeneric free function. The returned local belongs to that method, keeps its zero-based slot index, and retains the exact imported descriptor without nominal subtype reduction.

Null producers throw ArgumentNullException; foreign producers, non-composition results and unsupported body owners throw ArgumentException. The existing 1024 local limit throws InvalidDataException. Use StoreLocal before LoadLocal on every reachable path; wrong-value stores and uninitialized reads fail native body validation. Taking the local's address is rejected when writing. ClearBody retains locals but does not retain definite initialization. Ordinary DeclareLocal, authored composition signatures/fields and CLI projection stay gated. Runtime execution requires the experimental-compositions interpreter profile.

var producer = output.ImportExperimentalCompositionReference(factoryDefinition, core);
var slot = main.DeclareExperimentalCompositionResultLocal(producer);
main.Call(producer);
main.StoreLocal(slot);
main.LoadLocal(slot);
main.Call(output.ImportExperimentalCompositionReference(echoDefinition, core));
main.Emit(OpCode.Pop);
main.LoadConstant(42);
main.Return();

The compiled host checks exercise union, intersection, redundant intersection and wrapper result locals; Raven source-local emission is not enabled by this host API. The API adds controlled storage of an existing type contract, not a distinct kind of type or a restriction on structural types' eventual introspection support.

External reference wrappers with closed composition arguments can now be read in the experimental profile. ImportExperimentalCompositionReference requires an explicit IAssemblyResolver for their dependencies; the exact resolved definition must be an unconstrained reference class. Missing or incompatible definitions fail import. Default readers and CLI output remain rejected.

Imported composition storage admission (2026-10-14 development)

public void AssemblyBuilder.EnableExperimentalCompositionStorage(ImportedMethodReference producer);

Registers the exact closed reference compositions reachable through an imported result, including its constructed reference-wrapper arguments, for this output only. The producer must belong to this assembly and its return must contain a composition. Null throws ArgumentNullException; foreign or non-composition producers throw ArgumentException. Repeated registration is idempotent. This does not construct new compositions, reduce nominal bounds or admit open composition operands.

After registration, those descriptors work with ordinary DeclareLocal, reference-class instance AddField, MethodSignature and generic construction/substitution. Native body validation checks stores and reads. Compound byref parameters, value/static composition fields and CLI projection remain rejected. Runtime field addresses also reject, with or without verification. Use the experimental-compositions interpreter profile.

The experimental native reader now admits composition reference-class fields and nongeneric owned method signatures; the default reader remains closed. External intersection bounds still require finality resolution unavailable in this reader profile. Raven's generated async state machines use this storage admission with the exact imported Task result contract. See the linked composition experiment for executable evidence.

Authored reference compositions (2026-10-14 development)

AssemblyBuilder.CreateExperimentalReferenceComposition(ReferenceCompositionKind kind, params SignatureType[] types) returns an output-owned structural signature. Supply 2–256 closed nominal reference bounds; same-kind nesting flattens, duplicates collapse and a singleton becomes its remaining type. Closed generic reference bounds and composition arguments in closed reference wrappers are supported. Intersection bounds must be interfaces or classes open to extension (CLR final is rejected, including a local class made final after signature creation). Open, value, pointer and function bounds are outside this profile. Foreign or invalid operands throw ArgumentException; invalid graph mutations fail emission. Input arrays are copied.

The returned signature is admitted for native parameters, returns, locals, reference casts and type tokens. Emit with WriteNativeAssembly and optionally the NEOX binary container. CLI and PE reference projection reject admitted compositions. This is an explicit experimental extension to CLR signatures, which have no native union or intersection element type; no nominal carrier declaration is synthesized. Native interpreter execution requires experimental-compositions; JIT/AOT remain gated. Validation: the host test runner's --authored-compositions checks native roundtrip, normalization, ownership, unsupported bounds and finality mutation.

Structural method constraint inspection (2026-10-14, development)

The host C# metadata library can read closed structural method bounds from native NEOX using AssemblyDefinition.ReadNativeAssembly(image, allowExperimentalCompositions: true). This is native metadata inspection, not a CLI representation or guest runtime API. The ordinary reader rejects these bounds.

  • GenericMethodTypeConstraint(int ParameterIndex, SignatureType Bound) records a zero-based method parameter ordinal and its complete bound signature.
  • MethodDefinition.TypeConstraints returns a read-only snapshot of all supported nominal and structural method type bounds. Unsupported generic constraints throw InvalidDataException; an incomplete bound set is never returned.
  • MethodGenericParameterTypeInfo.GetTypeConstraints() returns the corresponding context-owned TypeInfo views, including ReferenceCompositionTypeInfo with its kind and constituents. Repeated resolution shares canonical type-view identity. Unsupported constraints or unresolved dependencies throw InvalidDataException.

For example, enumerate parameter.GetTypeConstraints() and inspect a returned ReferenceCompositionTypeInfo.Kind and .Constituents to distinguish an any-of union from an all-of intersection. These queries do not check supplied generic arguments or execute the method. Bounds remain closed reference compositions; open operands and final intersection classes reject. Closed hierarchy roots remain valid. Normalization can collapse duplicate operands to a nominal signature.

The older InterfaceConstraints and GetInterfaceConstraints() APIs are nominal-interface-only. They throw for a structurally encoded bound, including one collapsed by normalization, so existing consumers cannot silently erase its contract. CLI projection and callable import of structurally constrained methods remain unsupported. Type-parameter constraints on generic classes, authoring these bounds, Raven native emission and guest constraint reflection are separate pending work. Compared with CLR conjunctive nominal bounds, native signatures retain disjunction and explicit grouping; the cost is an opt-in native-only consumption contract. Validation: --structural-method-constraints in the metadata test executable covers JSON/binary roundtrip, context identity, mixed grouping, normalization, nominal compatibility, invalid bounds/ordinals/duplicates and unsupported consumer gates.

Native structural method constraint authoring

MethodBuilder.AddExperimentalStructuralConstraint(int parameterIndex, ReferenceCompositionKind kind, params SignatureType[] constituents) adds a native-only closed bound to a method parameter. The zero-based ordinal must exist; constituents are normalized using the assembly composition factory and must retain at least two distinct constituents. Local reference classes/interfaces and closed local generic reference constructions are admitted. Imported closed reference constituents are also admitted in unions, including closed generic constructions. External intersection operands additionally require imported definition snapshots proving they are extendable reference types. Open operands, value operands and final classes written in intersections reject. Null constituent arrays throw ArgumentNullException; invalid ordinals, duplicates, foreign/unsupported operands or a combined constraint count above 128 throw ArgumentException. Native output uses GenericConstraint.TypeBound; CLI output remains unavailable. MethodDefinition.TypeConstraints includes authored bounds, while the nominal-interface query rejects methods containing these bounds.

MakeGenericInstance checks structural bounds, and calls are rechecked on emission and graph serialization. Target unions require any alternative, target intersections all constituents, and source unions require complete alternative coverage. Nominal leaf checks use local inheritance/interface relationships and invariant closed construction identity. Closed classes can satisfy interface intersections. Forwarded method parameters are checked against the conjunction of the caller’s declared bounds at emission and serialization. Missing or weaker guarantees reject. Guaranteed nominal interface calls through method parameters are supported by the constrained-call overloads documented below. Generic inherited class relationships beyond the existing nominal model are not inferred. No conversions or variance are added by this API. Adding a bound after emitting a call cannot bypass validation.

Example: method.AddExperimentalStructuralConstraint(0, ReferenceCompositionKind.Union, responseType, errorType) writes a structural bound for the first method parameter, without generating a nominal carrier. The authored constraint fixture runs in the experimental interpreter with result 42. Raven emits/imports this bounded native method profile, including resolved external intersections. Generic owner constraint authoring and guest constraint reflection remain gaps. See the external union checkpoint below for three-assembly validation.

Importing structurally constrained native functions

AssemblyBuilder.ImportExperimentalConstrainedReference(MethodDefinition definition, AssemblyIdentity dependencyCoreLibrary, IAssemblyResolver? resolver = null) imports an explicitly selected native generic free function with at least one structural method bound. It preserves all method bounds in the private call contract, importing constituents into the consumer's scope. The function must be static, have no declaring type, native import or special implementation flags, and use an ordinary executable parameter/result signature. Closed reference bounds follow the native reader profile; open structural operands remain unsupported. Dependencies must resolve through the supplied catalog to consistent snapshots. Invalid metadata/profile/core or snapshot mismatches throw InvalidDataException; null required inputs throw ArgumentNullException. Ordinary callable imports continue to reject constrained methods outside their supported profile.

The returned ImportedMethodReference.MakeGenericInstance checks all imported bounds against consumer-scoped arguments. Call emission and serialization check them again. Interface conformance uses registered native definitions; class ancestry uses the existing explicit base contracts. Closed generic identity remains invariant. Source union arguments need complete coverage. Forwarded method parameters require sufficient declared caller bounds; generic-body trait calls remain unavailable. The import does not synthesize a nominal carrier or a CLI projection. Existing unconstrained imports retain their behavior. Native execution still requires the experimental runtime feature and runtime verification.

Validation includes a separately written metadata producer/consumer (result 42), invalid arguments, incomplete union coverage, default import/CLI gates, nominal constraint regression checks and existing composition import checks. Companion Raven uses this API for opt-in native free-function calls; source and separately compiled consumers cover interface union/intersection bounds and a closed Response<A> | B bound. This supersedes the pending native import statements above only for this profile.

Forwarding method parameters with closed structural bounds

A method whose parameter is constrained by A | B can forward that parameter to another method requiring A | B. A caller guaranteeing A & B can forward to a callee requiring both traits or a single guaranteed interface. Separate nominal bounds are considered together as a conjunction. A union guarantee does not imply an intersection; an unconstrained parameter does not imply either guarantee.

This uses bounded structural entailment over the existing closed bound signatures; it does not admit open operands such as Response<T> | Error. Provisional method references can carry caller parameters, but emission and serialization must prove those parameters from the caller’s recorded constraints. External-bound source authoring, generic-body trait calls and owner/type-parameter forwarding remain unsupported. The metadata fixture and the Raven source/library-consumer fixture execute through forwarded generic calls with result 42. Earlier blanket statements that method forwarding is unsupported are superseded by this bounded profile.

Interface calls guaranteed by structural bounds

The owned-target IILGenerator.CallConstrained(SignatureType implementingType, MethodBuilder target) overload now admits nongeneric abstract instance interface methods when the method parameter has an explicit structural bound that guarantees the target interface. Push a managed reference to that parameter (for example with LoadArgumentAddress) before the call. Native encoding uses existing borrowed callself; no schema or CLI representation is added. The raw Emit overload retains its existing OpCode.Call spelling. Operand validation and serialization reject insufficient guarantees or an incompatible receiver stack. Existing nominal-only static calls retain their earlier admission and Self substitution behavior.

An intersection guarantees each constituent trait. A union guarantees a target trait only if every alternative does; partial overlap is insufficient. The runtime verifier uses the same distinction when authorizing an interface/base view of a constrained parameter, retaining nominal inheritance and Self substitution at the leaves. Concrete execution still resolves and checks the actual implementation. Default builds do not admit structural bounds. External/constructed interface call authoring and owner-parameter support are not expanded by this slice. Raven’s tested source case uses a local intersection-constrained generic body calling two interface methods and returns 42.

This supersedes the blanket generic-body-trait gap above for owned nongeneric interface contracts. The APIs are host C# tooling; guest reflection APIs do not change. Compared with CLR constrained dispatch, this keeps the existing receiver/call behavior and extends only the native structural proof of the required interface.

2026-10-14 imported trait dispatch checkpoint: the explicit native composition profile now admits completed imported nongeneric interface methods through a structurally constrained method parameter. The receiver remains a managed parameter reference, encoded with borrowed callself. Every union alternative must guarantee the requested interface; intersections can supply it through nominal inheritance. Nominal-only static calls retain their existing validation. The Raven --structural-constraints probe compiles TraitLibrary.neox separately, then emits ExternalTraits.neox whose local LocalA & LocalB bounds inherit the imported interfaces. Its two method calls return 40 + 2 = 42 in the native interpreter. This adds no CLI carrier or metadata schema: default composition rejection remains. Direct external structural-bound authoring, constructed interface targets under structural bounds and open bound operands remain pending. The host metadata emitter owns admission; Raven retains its existing imported-interface emission path.

Closed constructed trait targets (2026-10-14): native structural method bounds now also authorize imported constructed interface calls when their closed guarantees prove the exact target construction. Reads<int> does not prove Reads<string>; every source-union alternative must prove the requested construction. Existing nominal/Self constrained calls retain their prior path. Raven's ConstructedTraits probe inherits ImportedReads<int> through a local intersection constituent and calls it using the existing borrowed native dispatch. No CLI encoding is added. Direct external structural-bound authoring and open operands remain unsupported.

External union constraint alternatives — 2026-10-14 development

The native MethodBuilder.AddExperimentalStructuralConstraint API now accepts output-owned imported closed reference alternatives in union bounds, including constructed interfaces such as ImportedReads<int> | ImportedReadsB. Constraint metadata retains the external type identity and exact generic arguments. Argument checks continue to require explicit nominal implementation/inheritance, with every source-union alternative covered. Matching member names are insufficient.

Raven uses its existing explicit native structural-composition capability contract; no CLI carrier, schema change or new compiler switch is introduced. Its constraint probe emits TraitLibrary.neox, then ExternalBoundLibrary.neox with these bounds, then a separate ExternalBoundConsumer.neox. Import resolution requires both exact native dependencies. Host tests reject mismatched constructed arguments, partially covered unions and direct external intersection operands; source diagnostics reject nonimplementing lookalikes and arguments satisfying neither alternative.

External bounds beneath any intersection remain rejected by this method-authoring API: the current snapshot reader cannot establish their extension eligibility without resolving external definitions. This is a reader/authoring gap, not a permanent type-system restriction. Local intersections and existing nominal/Self contracts are unchanged. Open operands, guest constraint reflection and JIT/AOT remain outside this slice. Compared with CLR constraints, the native signature preserves disjunction rather than changing it into a conjunctive nominal list.

Resolved external intersection bounds — 2026-10-14 development

Native method intersection bounds now admit imported closed reference types after importing their definition snapshots. The composition factory checks CLR-style finality and reference/value classification; a Raven closed hierarchy remains a valid bound because its hierarchy flag is distinct from finality. Interfaces remain nominal and require explicit implementation or declared interface inheritance. Matching member shape does not establish conformance.

AssemblyDefinition.ReadNativeAssembly(image, allowExperimentalCompositions, IAssemblyResolver? resolver) resolves each external intersection operand against an explicit exact-identity assembly snapshot. It checks the named definition, enclosing scope and generic arity, rejects final/value definitions, and caches resolved snapshots for the duration of the read. The two existing overloads remain available; without a resolver, external intersections fail closed. Default composition opt-in and native runtime verification are still required. Bodies remain opaque; this API does not load executable assemblies or infer interface implementation from members.

Raven's experimental catalog snapshots only the selected paths, then retries unresolved images as selected dependency snapshots become available. Returned references retain host input order. Missing dependencies, invalid metadata and cycles that prevent external-intersection validation fail explicitly; ordinary nominal cycles do not acquire a new resolver requirement. No adjacent assembly search occurs. The explicit native composition capability now admits closed conjunctive interface constructions in method bounds. Only intersection operands request definition-backed admission; ordinary .NET and nominal emission remain unchanged.

The probe builds an interface library, a constraint library with T: ImportedReads<int> & ImportedReadsB, and a separate consumer. Its generic body calls both interfaces. The catalog is supplied in reverse dependency order, and the negative consumer has matching methods but omits one required interface declaration. This replaces the earlier external-intersection authoring restriction for the closed profile. Open operands, generic owner constraint emission, guest constraint reflection and JIT/AOT qualification remain follow-up work. Like CLR nominal interfaces, declared relationships govern membership; unlike a CLR constraint list, native metadata also retains structural grouping and an introspectable intersection signature.

Authored structural tuple signatures (2026-10-14 development)

AssemblyBuilder.CreateExperimentalTuple(params SignatureType[] elements) returns an owned, opt-in native SignatureType. Its Tuple property is a TupleSignature with read-only ElementTypes: IReadOnlyList<SignatureType>. Other signature kinds have a null Tuple. The builder copies inputs; callers cannot mutate the shape. TupleSignature.Equals, GetHashCode and enclosing signature equality preserve position, duplicates and nesting. ToString() is diagnostic, not serialized identity.

The factory accepts one through 256 elements: supported scalars, owned/imported closed nominal signatures and already admitted nested tuples. Open parameters, Void, erased Value, RuntimeTypeHandle, arrays, borrows, pointers, functions and compositions are rejected as elements and as nested nominal type arguments in this bounded factory. This tooling profile has a 16-level nesting bound and a 4096-node validation budget. Null arrays throw ArgumentNullException; invalid/foreign elements and resource violations throw ArgumentException. Graph validation rechecks admission before serialization, including nominal owners whose metadata changed after creation.

WriteNativeAssembly() writes the ordered native Tuple signature node, without a Tuple TypeDef. Parameters, returns and locals retain exact tuple identity through body checking; reordered shapes do not implicitly convert. Write() and reference CLI projection reject an output that has admitted tuples with InvalidDataException. Unlike .NET ValueTuple authoring, this does not construct a generic nominal carrier. Use a runtime built with experimental-tuples. Native C# reader/import support and Raven lowering are not implemented by this authoring slice. Tuple constructor and positional-operation builder APIs also remain follow-ups; the executable fixture validates authored signatures and a native tuple type token.

Run dotnet run --project tools/metadata/NeoCLR.Metadata.Experimental.Tests -- --authored-tuples target/authored-tuples, then run the emitted AuthoredTuples.neox with the experimental interpreter (expected exit 42).

Reading and importing native tuples (2026-10-14 development)

AssemblyDefinition.ReadExperimentalTupleAssembly(ReadOnlySpan<byte> image, IAssemblyResolver? resolver = null) returns an immutable native declaration snapshot. TryGetSignature preserves ordered SignatureType.Tuple.ElementTypes, including duplicate/nested elements and closed nominal generic elements. Write() on that snapshot retains the original native image; it does not project to CLI. Normal ReadNativeAssembly overloads, including composition-only opt-in, continue to reject tuple signatures. Tuple opt-in does not enable unions/intersections. Malformed shapes, empty/oversized tuples, open or unsupported elements fail with InvalidDataException. Authoring-profile element and nesting limits still apply. Bodies remain opaque and require runtime verification. A general C# introspection TupleTypeView is not added by this slice; inspect the retained method signature.

AssemblyBuilder.ImportExperimentalTupleReference(MethodDefinition definition, AssemblyIdentity dependencyCoreLibrary, IAssemblyResolver? resolver = null) imports a nongeneric native free function with ordinary implementation metadata. It returns an output-owned callable reference and admits its tuple storage for native emission. Null definition/core arguments throw ArgumentNullException; invalid declarations, unsupported signatures and absent/mismatched dependencies throw InvalidDataException. Direct tuple signatures and tuples nested in supported closed nominal constructions are retained. Tuple-bearing array/byref/function callable signatures remain unsupported. External nominal element definitions require an explicit matching resolver; no implicit assembly loading occurs. Ordinary import rejects tuples even after an opt-in import has cached the same method. Consumers with admitted tuples reject CLI emission.

Validation covers immutable-image preservation, nested/repeated shape roundtrip, closed generic nominal elements, separate consumer re-emission, missing/resolved external dependencies, default/composition-only rejection and malformed/open tuples. The separate native consumer returns 42 through an imported producer function and contains verified tuple-forwarding methods. Tuple values are not yet constructed by the C# builder in this fixture; construction/element APIs and Raven lowering remain.

Native tuple value operations (2026-10-14 development)

MethodBuilder.GetILGenerator() now exposes these native-only operations:

  • NewTuple(SignatureType type) consumes one value per element, pushed in declaration order, and pushes the structural tuple value.
  • LoadTupleElement(SignatureType type, int index) consumes an exact tuple value and pushes its element at the zero-based index.
  • StoreTupleElement(SignatureType type, int index) consumes a tuple followed by a new element value and pushes the updated tuple copy. It does not write the original local; store the result explicitly to replace that local.

All three require an explicitly admitted, output-owned tuple signature. Null signatures throw ArgumentNullException; non-tuples/foreign signatures throw ArgumentException; out-of-range positions throw ArgumentOutOfRangeException. Instruction-budget and stack/type mismatches throw InvalidDataException (stack checks occur on native write). Exact receiver and element identity are enforced by the existing typed body checker.

Native encoding uses aggregate newobj and indexed ldfld/stfld, without nominal constructors or FieldDefs. The updated-copy store is a deliberate authoring contract: unlike CLR ValueTuple field mutation through an address, it returns the replacement value. It preserves value copying but requires explicit assignment by the caller. Managed element-address authoring is not added here. CLI projection still rejects outputs with admitted tuples; runtime execution requires experimental-tuples.

The separate producer/consumer fixture now executes nested tuple construction, imported echo, element reads and copy update, returning 42 only when the original local remains unchanged. Negative checks reject malformed operand signatures, indices, receivers, constructor elements and replacement values. This supersedes the earlier fixture limitation that only tuple-forwarding signatures were verified. Raven lowering remains a subsequent compiler slice.

Native tuple names in C# authoring/import (2026-10-14 development)

AssemblyBuilder.CreateExperimentalTuple(SignatureType[] elements, string?[] elementNames) copies both arrays and preserves native element names. TupleSignature.ElementNames is an immutable ordered IReadOnlyList<string?>; empty means all elements are unnamed. The original params SignatureType[] overload remains supported and emits the original unnamed array payload. The named overload uses the native { elements, names } payload.

A nonempty name array must match element count. Each present name must be nonempty, NUL-free, valid UTF-16 representable as UTF-8, at most 1024 UTF-8 bytes and unique among effective names (unnamed positions use ItemN). Invalid names/counts throw ArgumentException; null arrays throw ArgumentNullException. Existing element ownership, closedness, nesting and node-budget rules still apply.

Names do not affect TupleSignature or SignatureType equality/hashing. Named and unnamed tuples of the same ordered element types remain equal. The builder preserves each descriptive signature independently; callers must not use type equality to assert that names survived a round trip. ReadExperimentalTupleAssembly and ImportExperimentalTupleReference preserve names recursively, including differently named parameters/results with equal structural types. Native snapshots expose names through MethodDefinition.TryGetSignature. Invalid named shapes are rejected; ordinary readers and CLI output continue rejecting tuple contracts.

Compared with CLR ValueTuple plus TupleElementNamesAttribute, this stores names in the signature itself. New named payloads need matching tools; old unnamed payloads remain readable. Guest reflection name APIs and Raven native tuple import are not added here. The C# imported-call consumer returns 42 with named nested tuple values.

C# tuple introspection views (2026-10-14 development)

NeoCLR.Metadata.Experimental.Introspection.TupleTypeInfo is a read-only, non-nominal signature view returned by MetadataLoadContext.ResolveSignature and method parameter/result inspection. ElementTypes: IReadOnlyList<TypeInfo> keeps order, duplicates and nesting. ElementNames: IReadOnlyList<string?> has one entry per element, including null for unnamed elements. Both lists are immutable copies. DisplayName is tuple<...> using element displays; IsNominalType is false.

Views retain descriptive names for each signature rather than interning by structural equality. Reference equality of these views is not a structural-type equality API; SignatureType equality and runtime TypeIdentity remain positional. Projection uses this metadata context's explicit dependency catalog and owner/method substitutions; unsupported or excessive nesting fails with InvalidDataException. No nominal tuple declaration, fields or constructors are synthesized in this host API.

The view enables Raven's explicit native tuple import. It is distinct from guest System.Introspection.TupleTypeInfo, whose ElementNames query returns effective names with positional ItemN defaults rather than nullable declared-name entries. Focused tests cover nested views and distinct return/parameter names on equal types; the separate Raven consumer executes imported named tuples with result 42.

Combined structural reads (2026-10-15 development)

AssemblyDefinition.ReadExperimentalTupleAssembly(ReadOnlySpan<byte> image, IAssemblyResolver? resolver = null, bool allowExperimentalCompositions = false) reads native tuple signatures, optionally admitting union/intersection signatures in the same image. Supply a resolver for external definitions. Invalid or unresolved signatures fail validation; this does not enable CLI projection. The default remains tuple-only for existing host callers. Native Raven projects explicitly select combined admission. This host metadata API is documented here, not in the guest RavenDoc type selection.

Authored standalone libraries (2026-10-15 development)

NativeModuleContainer.WriteLibraryBinary(AssemblyBuilder assembly) validates the authored graph with its explicit dependency contracts and serializes native JSON under the existing 32 MiB library budget, then writes schema 3/4 standalone NEOX bounded to 16 MiB. It preserves native structural signatures without a CLI projection. Null throws ArgumentNullException; invalid graphs or exceeded bounds throw InvalidDataException. Application writer budgets are unchanged. This host API is covered by this manual reference, outside guest RavenDoc.

Closed value union alternatives (2026-10-15 development)

CreateExperimentalReferenceComposition retains its legacy API name but now admits closed scalar and nominal value alternatives for Union, including imported value definitions. Native reads apply the same rule. Intersection continues to reject value operands. Void, erased Value, RuntimeTypeHandle, intrinsic String, open types and structural tuple alternatives remain outside this bounded factory. Value payload construction requires explicit boxing and extraction copies through explicit unboxing; this does not give the union a nominal Object/ValueType base. The native signature is preserved and CLI projection remains unsupported. See the integration contract for validation and remaining generic wrapper/byref limitations.

Managed structural parameter signatures (2026-10-15 development)

SignatureType.ByReference(elementType) may target a direct admitted union or intersection in a method parameter. Ownership and structural storage admission remain required. Native readers preserve the wrapper when experimental composition reads are enabled; default reads and CLI projection reject it. Nested composition wrapper targets remain rejected by authoring. IILGenerator.LoadObject and StoreObject use the exact structural element signature; writes must satisfy that slot's type. These are managed interpreter slots, not native pointer/ABI support.

Structural callback element reads (2026-10-15 development)

With composition reading enabled, native SignatureType.Function parameter and result shapes preserve admitted composition elements through declaration materialization. Default reads still reject structural compositions. The host roundtrip covers a callback accepting and returning a union. Interpreter execution is bounded to exact nongeneric callback targets without composition-bearing owners; CLI projection of these shapes is unsupported. No nominal delegate or union type is synthesized.

Composition-enabled native declaration reads preserve generic method scope and structural arguments in nominal value wrappers. This is metadata introspection support; callable import and runtime execution have separate admission rules. Open union constituents remain unsupported.

Scoped generic composition constituents

AssemblyBuilder.CreateExperimentalReferenceComposition(kind, types) now accepts method/type parameters inside owned or imported nominal generic constituents. For example, a union may contain Response<SignatureType.MethodParameter(0)>. The factory checks ownership and bounded shape; the containing signature checks actual parameter scope through existing owner validation. Wrong-scope uses throw ArgumentException. A bare generic parameter is still not an admitted constituent. Unions retain value alternatives; intersections retain nominal extendable reference bounds. Native opt-in reads preserve scoped indices. GenericMethodInstance.Signature and ConstructedMethodReference.Signature now substitute inside compositions. Normalization remains order-independent without nominal subtype reduction.

Validation: authored native roundtrips, method/owner substitutions, wrong-scope rejection, the Raven open-generic consumer (42), and 58 structural interpreter tests. No guest API selection or generated signature changes are required. CLI projection, JIT/AOT representation and arbitrary symbolic structural constraints remain outside this validated surface.

Callable composition authoring

CreateExperimentalReferenceComposition(Union, types) now admits function alternatives with recursively checked parameter/result signatures, including a function whose result is another union. CastReference accepts the callable reference category for exact union injection/narrowing; the graph stack verifier and native reader agree. Ownership, generic scope and composition limits still apply. Function intersection bounds remain rejected, and tuple/byref/pointer components retain the current composition admission limits. CLI carrier projection is unchanged. --authored-compositions verifies native round-trip and checked-cast authoring; --reference-compositions verifies reader admission, including existing generic-method support. Runtime/backend limits remain separately documented in structural operations.

Function constituents now recursively import into consumer ownership through ImportExperimentalCompositionReference, retaining the existing composition opt-in. Emit(OpCode.Isinst, functionType)/IsInstance(functionType) accept function shapes; ordinary stack verification still requires a reference-compatible input. The host regression covers import ownership, type-test emission and nested union results.

Structural record instance fields (2026-10-15 development)

TypeBuilder.AddField now accepts experimental union/intersection signatures in value-record instance fields as well as reference classes. The opted-in native reader preserves those field signatures; use FieldDefinition.TryGetSignature to inspect them. Static composition fields and interface instance storage remain rejected. Authored signatures retain ownership checks; this does not enable CLI projection of structural types. Generic wrappers and direct record declarations now follow the same runtime storage rule. The matching runtime/backend is required.

Structural tuple method references (2026-10-15)

AssemblyBuilder.CreateMethodReference accepts ordered structural tuple parameters and results, including tuples nested in imported generic arguments. Names remain in the signature and do not affect identity. Ownership, parameter scope and constructor validation still apply. These references require native output; Write/CLI projection rejects structural tuples. The imported Range consumer validates direct and Result-wrapped tuple results across an assembly boundary.

Unified native metadata reads (2026-10-15)

AssemblyDefinition.ReadNativeAssembly(image, resolver) and Raven's NeoClrMetadataReference.ReadAssembly(image, bootstrap, resolver) now read admitted nominal, union, intersection and tuple signatures together. The composition Boolean and separate experimental reader entry points are removed. NeoClrReferenceCatalog.Read and ReadNative no longer accept composition/tuple flags. Migrate callers to these normal APIs. Selected dependency resolution remains explicit and order-independent; missing, mismatched or non-extendable intersection bounds still reject. CLI projection remains a separate restricted contract, not a substitute native representation.

Focused checks cover tuple authoring/import, union/intersection authoring/import, external structural constraints, source tuple mutation and source constrained library consumers. The legacy full metadata suite has six pre-existing failures around host core attribute limits and stale Object/local-budget expectations; these do not qualify as passing coverage and are tracked for integration cleanup.

Metadata reader integration qualification (2026-10-15)

The CLI declaration reader accepts at most 8,192 custom-attribute rows, increased from 4,096 because the valid tooling test assembly now has 4,217 rows. Per-member 256-attribute limits, image/signature/blob budgets and structural validation remain unchanged. Boundary tests accept 8,192 and reject 8,193 attributes in persisted CLR metadata. This is a bounded tooling capacity change, not a native type-system limit. The full host metadata suite now passes 175/175, including corrected expectations for the existing 1,024-local limit and concrete public virtual direct calls.

Runtime interface variance metadata

The runtime TypeDef JSON schema accepts an optional generic_variance vector: invariant, covariant, contravariant, aligned with generic_parameters. An absent/empty vector preserves invariance. The loader rejects arity mismatch, unknown values, variant class/value declarations and unsafe interface signature positions. The SDK supports explicit interface annotations and native/CLI metadata round trips. Raven integration and native execution qualification are tracked separately.

Interpreter reference conversion now uses the verified annotations for nominal interface views and calls, retaining receiver identity. Native specialization explicitly rejects used variant interfaces before erasing generic identity. These are low-level runtime capabilities; existing Raven public interfaces, including Sliceable, remain invariant, and Result payload conversion is not implemented.

Read-only variance API

These host metadata APIs are documented here because RavenDoc's guest reference assembly does not include the experimental C# SDK.

  • Model.GenericVariance: Invariant, Covariant, Contravariant, describing declaration intent without proving signature safety or assignability.
  • Model.TypeDefinition.GenericParameterVariance: IReadOnlyList<GenericVariance>?: immutable native annotations in parameter order, with exactly GenericArity entries. Missing/empty native annotations yield invariant entries; nongeneric native declarations yield an empty list. CLI snapshots and authored generic definitions also expose their annotations. Null means the declaration does not materialize this fact.
  • Introspection.GenericParameterTypeInfo.Variance: GenericVariance: the native annotation for Position. Throws NotSupportedException when the declaration's variance list is unavailable. Parameter identity remains owner plus position.

AssemblyDefinition.ReadNativeAssembly rejects unknown annotation values, arity mismatches and non-invariant annotations on noninterfaces with InvalidDataException. Runtime loading additionally verifies signature polarity. AssemblyDefinition.Write copies the original native image, including annotations. AssemblyBuilder.ImportReference retains variant interface declarations; NativeAssemblyDefinition.CreateReferenceAssembly preserves annotations as CLI generic-parameter flags. Native binding checks reject a mismatch between reference and runtime annotations. Invariant input retains its existing behavior.

For a native Producer<T> declaring covariant, inspect definition.GenericParameterVariance[0] == GenericVariance.Covariant after checking that the list is available. This is metadata inspection, not an SDK conversion test. The focused SDK checks exercise native round trips, defaults, introspection and erasure guards.

Explicit interface variance authoring

TypeBuilder.SetVariance(int parameterIndex, GenericVariance variance) sets one interface parameter annotation. Parameters are invariant by default. Invalid ordinals, unknown enum values and noninterface variant owners throw ArgumentException. A write revalidates the complete declaration and throws InvalidDataException for unsafe positions, including varying parameters inside invariant wrappers or writable arrays/byrefs. Nested annotated interfaces compose polarity. Static contracts, Self and generic interface methods remain outside the current variant profile.

For a producer, call producer.SetVariance(0, GenericVariance.Covariant) and declare an instance method returning SignatureType.TypeParameter(0). A consumer instead uses Contravariant and consumes that parameter. The focused SDK fixture below the read-only API section exercises both native and CLI emission and runtime loading. SetVariance does not make arbitrary value arguments convertible or provide Result mapping; declaration validation and call-site reference conversions are separate.

AssemblyBuilder.SetInterfaceVariance(ImportedTypeReference reference, IEnumerable<GenericVariance> annotations) records a resolved external interface's annotations before CompleteInterfaceReference. The open reference must belong to the output and have one valid annotation per parameter. Values are copied; invalid or conflicting annotations throw ArgumentException, and calls after completion throw InvalidOperationException. Like AddInterfaceConversion, this is an explicit semantic-provider assertion tied to the dependency, not independent verification. The runtime must validate the actual loaded definitions.

SDK call/return storage checks now admit declared reference-only interface variance, including nested local/imported interfaces. Exact conformance wins; multiple other compatible views reject. Writable aliases, value boxing, numeric conversions and mutable-array covariance remain excluded. Equal value arguments remain exact. Intrinsic String reference arguments use the explicitly authored/imported String declaration for nominal interface relationships. SDK validation recognizes imported interface definitions as well as authored contracts; runtime dispatch adapts the String representation without copying its UTF-8 payload. Local class arguments with explicitly registered imported bases now use the same ancestry proof as ordinary reference conversion, including transitive local bases. This applies in covariant, contravariant and nested interface positions; reverse and unrelated-class conversions still reject. A separately compiled Raven consumer qualifies this through interpreter, AOT and managed JIT with actual object identity and inherited storage mutation. Generic class bases remain unsupported. Imported class arguments also inherit interface views through explicitly registered DeclareClassBase chains. The metadata writer requires the complete chain; a matching name or an unregistered ancestor is insufficient. This applies to both producer and consumer conversions and preserves reverse-conversion rejection.

Native compiler variance bridge

The unstable Rust native_metadata bridge exposes retain_interface_shape and retain_interface_slot for verified source definitions, interface_has_variance and interface_view for resolution, and interface_slot_peers and interface_shape_arguments for selection dependencies. These are compiler-only in-memory facts, excluded from serialization and guest RavenDoc. Invalid shape indices or arity return Fault; callers must supply verified source modules and valid function indices. They preserve source identities through private shape renumbering; they do not define new nominal inheritance or public guest types.

native_metadata::restore_interface_proofs(target, original, map_type) preserves trusted interface/slot, closed array-backing, String-interface and native Object-root facts through a row-preserving compiler rewrite. It requires matching type/function row counts and applies the same nominal type remapping to retained interface arguments and array elements. It returns Fault on row mismatch or mapping failure. This compiler bridge does not deserialize proof fields from external metadata.

native_metadata::retain_object_reference_root(definition) records the verified Object root's reference role before a private native rename. Callers must supply verified compiler IR; a non-Object name, value type or generic declaration returns Fault. The private marker survives row-preserving rewrites but is omitted on serialization; attempts to inject it into external metadata reject. This preserves interface-to-Object conversions inside variance without adding boxing or changing String's distinct representation. It does not install a second Object slot registry.

native_metadata::retain_array_shape(target, source, index, arguments) retains the closed element identity of the verified source array backing on its private native shape. Callers must supply verified compiler IR. A missing source row or malformed backing arity/reference kind returns Fault; a non-backing row is ignored. The marker is omitted by serialization, rejected in external metadata and remapped through restore_interface_proofs. It allows variance to follow the backing's existing nominal interfaces after specialization; it adds no array-element conversion or layout.

native_metadata::retain_string_view(target, source, interface) retains verified intrinsic String conformance on a closed native interface shape. Callers supply verified source IR and its original unlowered interface identity. A non-interface or an interface String does not implement records no conformance. The private flag survives trusted row-preserving rewrites; serialization omits it and external metadata cannot supply it. It grants neither structural conformance nor a new String layout. Native dispatch separately adapts String arguments/results to the existing Object/interface pointer representation.

Constructed native class bases

Model.TypeDefinition.BaseTypeSignature: SignatureType? preserves local native constructed class bases, including nested nominal/array arguments and owner-scoped type parameters. The existing BaseType property identifies the base definition; it does not carry construction arguments. Null from BaseTypeSignature means no recorded native/authored base. CLI snapshots throw NotSupportedException because base-signature materialization is not implemented there.

Introspection.NominalTypeInfo.BaseType: TypeInfo? now resolves the full signature using that definition's canonical parameter views. Introspection.ConstructedTypeInfo.BaseType: TypeInfo? substitutes that construction's arguments. For Middle<T> : Base<T[]>, the open view contains Middle's T and Middle<int>'s base contains int[]. Repeated queries use canonical same-context type identities. Missing dependencies fail through the explicit metadata resolver; no assembly is loaded implicitly.

Both nominal and constructed GetInterfaces include interfaces inherited through native class ancestors, with substitution at every edge. GetDeclaredInterfaces continues to return only declared relationships. Inheritance cycles, including expanding generic cycles, reject rather than recursively expanding indefinitely.

ReadNativeAssembly accepts these local native base constructions and preserves the original immutable image on Write. Wrong arity, unbound base definitions, out-of-scope parameters, sealed bases and invalid base categories reject with InvalidDataException. Explicitly bound external constructed bases also preserve their arguments and exact assembly scope. Generic class-layout authoring remains a gap. CreateReferenceAssembly still rejects class inheritance rather than projecting an incomplete hierarchy. These are metadata-only APIs, not guest native execution qualification. SDK reader/introspection and existing context/inheritance checks pass.

External constructed class bases

ReadNativeAssembly also accepts a constructed external class base when its native binding matches the definition name and argument arity. The binding must describe a top-level reference type in an explicitly registered dependency. BaseTypeSignature preserves declaration-scoped arguments; BaseType retains the definition reference. NominalTypeInfo.BaseType and ConstructedTypeInfo.BaseType resolve and substitute the full signature through the caller's explicit MetadataLoadContext. GetInterfaces follows that substituted dependency base and its inherited interface contracts.

For Child<T> : Dependency.Base<T[]>, Child<int>'s base is the canonical Dependency.Base<int[]> in the same context. No metadata is fetched implicitly. Missing/mismatched bindings, invalid argument scope and value-type bindings reject with InvalidDataException. Missing/wrong-version dependencies reject at resolution. Dependency declaration legality remains subject to runtime verification; the consumer binding alone does not prove a base is extendable. Both library and executable NEOX wrappers retain exact image bytes on Write. Inheritance CLI projection and generic class-layout authoring remain unsupported.

Focused reader checks exercise open/closed identity, inherited generic interfaces, round trips and invalid bindings, alongside existing local/nongeneric external base and metadata-introspection regressions. This is host metadata support, not a new guest reflection or Raven/native execution claim.

Generic class authoring over ordinary bases

AssemblyBuilder.AddGenericClass(namespace, name, parameterNames, TypeBuilder baseType, visibility) now accepts an owned, nonsealed, nongeneric top-level reference class, including the native Object root. The equivalent manually attached TypeDefinition is accepted. Foreign, static, value, interface, sealed or unbound generic bases reject. This does not yet author constructed generic bases or nested derived classes over ordinary bases.

Derived constructors must explicitly initialize their direct base exactly once before field access or return. Inherited storage precedes the derived class's own fields. Closed instances can upcast to that base, including in covariant interface argument positions; class constructions themselves remain invariant. CLI field accesses on generic owners now encode the owner construction rather than using a bare FieldDef token, preserving correct field offsets with inherited storage. Native signatures retain the existing named base edge.

SDK/CLR tests cover integer/reference storage, base initialization, upcast identity and existing generic-class/Object-root behavior. See the retained native consumer under docs/validation/generic-class-base. Generic base construction authoring and Raven emitter eligibility remain open. Native AOT constructor lowering now accepts independent scalar constants and supported arithmetic/conversions before the leading base call, in addition to forwarded arguments. Receiver access, helper calls, stores and branches in that prefix remain backend gaps, not an alternative to .NET semantics.

Constructed class base authoring

The following overloads retain an owned constructed class base:

TypeBuilder AssemblyBuilder.AddClass(string @namespace, string name,
    GenericTypeInstance baseType, TypeVisibility visibility = TypeVisibility.Public);
TypeBuilder AssemblyBuilder.AddGenericClass(string @namespace, string name,
    IEnumerable<string> genericParameterNames, GenericTypeInstance baseType,
    TypeVisibility visibility = TypeVisibility.Public);

The base must be an attached nonsealed, top-level reference class in this output. Nongeneric children require closed arguments. Generic children interpret type parameter ordinals in the child's declaration scope, including reordered and nested arguments. Method parameters, out-of-scope arguments, foreign owners, interfaces, value types and sealed classes reject with ArgumentException; null bases/parameter sequences throw ArgumentNullException. These overloads do not enable external constructed base authoring or generic class virtual slots.

TypeDefinition.BaseTypeSignature retains the authored construction; BaseType still identifies its definition. Native output writes the constructed base signature; CLI output uses a TypeSpec extends entry. No encoding version or Runtime Contract change is needed. Ancestry conversions and inherited interface contracts substitute each edge, with exact class arguments: classes remain invariant. Closed inherited storage and calls retain their owning construction.

MethodBuilder.Call(ConstructedMethodReference) and its IL generator/Emit(Call) equivalents can initialize the current constructor's exact direct constructed base. The reference must name the right definition and arguments. Initialization must occur exactly once before receiver access/escape or return; Write validates flow and rejects invalid initialization with InvalidDataException. NewObject continues to allocate a new instance. Native backend initializer-expression limits remain in force.

The executable fixture in docs/validation/constructed-class-base covers reordered parameters, a closed leaf over a generic intermediate base, integer/reference storage, nominal upcasts, inherited generic interfaces and rejection boundaries. Raven's neoCLR adapter now emits owned constructed bases and imports those hierarchies from native dependencies. The deferred binding and external authoring APIs below also support recursive source base arguments. Generic class virtual slots remain a gap.

Deferred constructed base binding (2026-10-16)

TypeBuilder.SetBaseType(GenericTypeInstance baseType) binds an owned constructed base after a root class identity is declared and before its fields or methods. This supports Node : Base<Node> without erasing or replacing generic arguments. The owner must be an ordinary top-level root class; binding an explicit base twice or binding after members throws InvalidOperationException. Foreign, sealed, nonclass, out-of-scope and cyclic base-definition edges throw ArgumentException before mutation. Type-argument recursion is allowed; inheritance cycles are not.

The SDK fixture in docs/validation/constructed-class-base executes an inherited self-reference field and derived field through a recursive base, alongside the existing reordered generic hierarchy. CLR, interpreter, AOT and managed JIT return 42; native cleanup/sanitizers and all 178 SDK contracts pass. This follows the CLR model of recursive nominal generic signatures. Encoding, Runtime Contracts and ABI are unchanged; no structural features are enabled. Raven integration and external constructed base authoring are separate next slices.

SDK external constructed base authoring (2026-10-16)

CompleteClassBaseReference now accepts an unconstructed generic definition as well as a nongeneric definition. The host supplies the resolved public method contracts, complete declared instance field count (including private storage), and nominal base/interface edges. Complete each ancestor definition separately; methods must belong to that definition. These are trusted compiler facts, not a substitute for checking the dependency's visibility, extensibility and constraints. Exact artifact identity remains required when linking.

TypeBuilder.SetBaseType(ImportedTypeReference baseType) binds a complete external construction to a top-level root class before its members. It supports generic children with declaration-scoped arguments and nongeneric children with closed arguments. Missing contracts, wrong ownership, unbound or out-of-scope arguments throw ArgumentException; repeated/late binding or unsupported owners throw InvalidOperationException, before mutation. AddClass also accepts a closed external construction registered this way. BaseTypeSignature retains arguments.

Call(ImportedConstructedMethodReference) accepts a constructor only as the exact direct-base initializer of a constructor. Protected access and exactly-once current receiver initialization remain checked. It does not allow arbitrary constructor calls on existing objects. Dependency methods/interfaces and ancestry substitute each construction while layout counts remain definition-owned. Generic classes remain invariant, and interface conformance remains nominal and explicit.

CLI output uses TypeSpec extends entries; native output uses existing constructed signatures and arity-matched dependency definition bindings. No encoding version, ABI or Runtime Contract change is needed. Generic reference-class virtual slots remain unsupported. The SDK fixture in docs/validation/external-constructed-class-base covers a protected generic base constructor, reordered child parameters, private base and own storage, closed value/reference payloads, transitive upcasts and inherited generic-interface dispatch. CLR/interpreter/AOT/JIT return 42 with native cleanup and AOT sanitizers; all 179 SDK checks and API snapshot checks pass. Raven source qualification now also passes for a separate-provider consumer, including recursive external base arguments and protected initialization; see docs/validation/constructed-class-base/raven. Structural work remains parked.

Concrete generic class virtual slots (2026-10-16)

The SDK now permits AddVirtualMethod and AddOverride on concrete generic reference classes. Methods themselves remain nongeneric. Override parameters, result and passing modes must match the inherited contract after substituting each constructed base edge. The native metadata reader performs the same substitution and rejects incompatible results; definition ordinals are not compared as if they belonged to the same generic owner.

CallVirtual(ConstructedMethodReference) and Emit(Callvirt, ...) accept virtual reference-class contracts as well as interfaces. Call still invokes the selected concrete base body directly, so base calls do not redispatch into the override. This follows CLR nominal virtual-slot semantics. Class constructions remain invariant, and nothing infers nominal interface implementation from member shape.

AOT and managed JIT specialization retain the exact closed base-slot signature, then discover overrides among the selected closed reference shapes. Each ancestry edge substitutes its own owner arguments, including Derived<Unused,T> : Base<T>. Existing closed-world type/function limits and native dispatch thunks remain in force. There is no native format, ABI, Runtime Contract or boxing change.

The retained docs/validation/generic-class-virtual fixture returns 42 in CLR, interpreter, AOT and managed JIT for integer/reference payloads and direct base calls. It includes SDK and native-reader rejection of incompatible override results. A specialization regression verifies an override that never calls its base; all 14 specialization tests pass. Native cleanup and AOT sanitizers pass. This is macOS ARM64 development qualification. Generic methods, abstract generic class authoring, generic Object override qualification and Raven emission/import of these virtual slots remain separate work; structural types remain parked.

Imported concrete generic virtual slots (2026-10-16)

CreateMethodReference accepts nongeneric virtual methods on generic reference class definitions. Construct the reference with exact owner arguments before calling. CallVirtual dispatches to the closed override; Call invokes a public concrete body directly, including an explicit base call. Abstract direct calls and abstract generic class-slot authoring remain rejected. This matches the existing nongeneric reference contract and CLR dispatch semantics.

The external constructed-base fixture now exercises reordered child arguments, virtual Get and Echo overrides, direct imported base calls, integer/reference payloads and inherited interface dispatch. CLR, interpreter, AOT and managed JIT return 42, including native cleanup and AOT sanitizers. No encoding, ABI or Runtime Contract change. Raven emission/import remains the next integration step.

Abstract generic class authoring (2026-10-16)

TypeBuilder.SetAbstractClass and TypeDefinition.SetAbstractClass now accept ordinary top-level generic reference classes. The native reader preserves the abstract flag alongside owner parameters. Public nongeneric abstract slots use the existing virtual contract, with inherited signatures substituted through each base edge, including reordered parameters. This follows CLR abstract-class rules; there is no new metadata encoding, ABI or Runtime Contract configuration.

The generic-class-virtual/run.py --abstract SDK consumer returns 42 in CLR, interpreter, AOT and managed JIT, with native cleanup and AOT sanitizers. It covers an abstract Base<T>, concrete Derived<Unused,T>, abstract and concrete slot calls, direct concrete base calls, and integer/reference payloads. SDK checks reject constructing an abstract generic type, leaving an inherited abstract slot unimplemented on a concrete child, and calling an abstract method directly. An abstract child may defer implementation. Generic methods, nested abstract classes and generic closed hierarchies remain outside this slice. Raven admission and imported abstract contracts still need separate qualification.

Raven and imported abstract generic bases (2026-10-16)

The native adapter now opts into AllowsAbstractGenericClasses, a default-off shared planning capability. It marks generic class definitions abstract before attaching their bodyless slots. Imported native abstract methods preserve virtual and abstract flags on generic owner definitions; constructed call references retain exact owner arguments. SDK CreateMethodReference now accepts these abstract class contracts, while direct calls to them remain rejected. Explicit calls to concrete base methods remain direct. There is no erased generic information or new Runtime Contract configuration, metadata encoding or runtime ABI.

This follows .NET nominal abstract-class semantics: concrete children must provide compatible implementations after base-argument substitution; abstract owners cannot be instantiated. SDK rejection checks and the focused Raven capability/CLR tests cover these boundaries. The retained generic-class-virtual/raven runner supports --abstract, both locally and with --imported; consumers exercise Derived<Unused,T> and a consumer-owned override over Base<T>, abstract calls, concrete base calls, integer/reference payloads and identity. Interpreter, AOT and managed JIT return 42, including native cleanup and AOT sanitizers on macOS ARM64. This is development support on Raven codex/neoclr with the matching NeoCLR main SDK/runtime, not a Raven-main merge. Generic virtual methods, generic closed hierarchies and broader constrained dependency imports remain separate work. Structural types and Sliceable/Result variance stay parked.

Imported class constraints

These are host SDK APIs, not guest reflection APIs. They follow CLR generic class constraint semantics within the bounded profile described below.

API Contract
AssemblyBuilder.SetSpecialConstraints(ImportedTypeReference reference, int parameterIndex, TypeParameterConstraints constraints) Register nonzero ReferenceType, ValueType, DefaultConstructor or compatible combinations on an output-owned unconstructed top-level generic class or value type. ReferenceType and ValueType conflict; ValueType conflicts with a nominal class bound. Unlike the local builder setter, None does not clear dependency facts.
AssemblyBuilder.AddBaseTypeConstraint(ImportedTypeReference reference, int parameterIndex, ImportedTypeReference baseType) Register one nongeneric nominal class bound per parameter. Both references belong to the output. Closed arguments must have the bound's nominal ancestry. No structural conformance is inferred.
AssemblyBuilder.DeclareDefaultConstructor(ImportedTypeReference reference, bool available) Record whether a dependency reference class is concrete and has a public parameterless constructor. The host inspects the actual declaration. Value/interface, constructed, nested and foreign references reject.
ImportedTypeReference.SpecialConstraints Read-only dictionary of registered flags by definition parameter ordinal. Constructions query the same definition contract.
ImportedTypeReference.TypeConstraints Read-only dictionary of registered nominal bound signatures by definition parameter ordinal.
GenericParameterTypeInfo.SpecialConstraints Native reference/value/default-constructor flags for the declaring parameter.
GenericParameterTypeInfo.GetTypeConstraints() Read-only list of native nominal bound type views, resolved in the same metadata context with exact identity.

Registration is idempotent for identical facts; conflicting repeated facts throw InvalidDataException. Invalid owners, indices, categories, combinations and bounds throw ArgumentException; null references throw ArgumentNullException. A false constructor fact remains an explicit fact; unknown external constructors cannot satisfy new(). These registrations do not load dependencies or alter provider metadata. The provider's native declarations remain authoritative at linking.

MakeGenericInstance checks known closed requirements immediately. Use/write repeats validation, including after late registrations; local constructor completeness is checked once the declaration graph is complete. Invalid arguments throw ArgumentException (write paths may wrap this in InvalidDataException). Symbolic base arguments must prove requirements before emission. Value types satisfy constructor requirements; abstract classes and nonpublic/nonzero-arity constructors do not.

ReadNativeAssembly now materializes special flags and the existing owned nongeneric class-bound profile. Legacy ImportReference(TypeDefinition, ...) rejects constrained owners; use the explicit contracts above. Loaded nominal bounds are inspected through GenericParameterTypeInfo.GetTypeConstraints; the authoring-oriented TypeDefinition.GenericConstraints still throws NotSupportedException for those snapshots rather than returning an empty list. Unsupported snapshot formats likewise reject constraint introspection instead of inventing empty constraints.

No metadata schema change. Constrained generic methods, interface/constructed nominal type bounds and constrained interface/value owner imports remain outside this slice. See qualification.

Native function-kind constraint (feature branch, 2026-10-16)

TypeParameterConstraints.FunctionType (32) means a native structural function signature, with any parameter/result signature. It is not a CLI flag or a nominal System.Delegate bound. TypeBuilder.SetSpecialConstraints and AssemblyBuilder.SetSpecialConstraints(ImportedTypeReference, int, TypeParameterConstraints) accept it as a standalone requirement in this initial profile; combinations and nominal bounds reject with ArgumentException. Generic arguments must be SignatureType.Function(...); nominal types, arrays of functions and primitives do not satisfy it. Scoped symbolic arguments are checked after substitution and symbolic base requirements use the existing proof checks.

Native metadata stores FunctionType. ReadNativeAssembly and GenericParameterTypeInfo.SpecialConstraints retain it. Use NativeModuleContainer.WriteLibraryBinary for authored containers. CLI export and reference projection throw InvalidDataException rather than invent a CLR encoding or erase this requirement. Older native readers reject the unknown kind. No new invocation operation is introduced; exact function signatures stay intact.

This is isolated feature-branch groundwork. Raven syntax, function-list APIs and dynamic invocation are not delivered by this SDK addition. See qualification.

Method category constraints

MethodBuilder.SetSpecialConstraints(int parameterIndex, TypeParameterConstraints constraints) and MethodDefinition.SetSpecialConstraints(int parameterIndex, TypeParameterConstraints constraints) accept ReferenceType, ValueType, DefaultConstructor and compatible combinations, or standalone native FunctionType; None clears the flags. Reference/value flags conflict. Unknown flags, invalid ordinals and FunctionType combined with another flag or type bound throw ArgumentException. Ordinary category flags can coexist with nominal interface bounds. Loaded definitions are immutable (InvalidOperationException). MethodDefinition.SpecialConstraints exposes a read-only dictionary by ordinal (unsupported loaded CLI constraints throw InvalidDataException instead of appearing empty); MethodGenericParameterTypeInfo.SpecialConstraints returns the flags for that parameter. Type bounds remain separately available through TypeConstraints/GetTypeConstraints; the legacy interface-only query rejects a category constraint rather than return an incomplete constraint view.

Ordinary categories use the existing type-argument validator and CLI GenericParameterAttributes values 4/8/16. Native reads/writes, CLI reads/writes, reference projection and callable import preserve the flags. MakeGenericInstance rejects incompatible concrete arguments; DefaultConstructor requires a value type or a nonabstract class with a public parameterless constructor. Forwarded method and declaring-type parameters must prove the required flags; ValueType implies DefaultConstructor. Calls are revalidated on write. CLI bit 32 (AllowByRefLike) is unsupported and is never interpreted as native FunctionType. Raven's native adapter now emits and imports these categories.

NeoCLR.Metadata.Experimental.Tests --method-categories covers these contracts, combined interface/category bounds, imported rejection, CLI execution and all three snapshot paths. Native specialization admits these categories through shared runtime validation before closing the method. This is host SDK/backend support, not a change to guest Enum signatures.

Native authoring, snapshot reads and AssemblyBuilder.ImportReference also preserve the standalone FunctionType requirement. MakeGenericInstance rejects nonfunction arguments. Forwarded method parameters require a caller function constraint when emitting a call; writing revalidates this proof after edits. CLI executable/reference output rejects these native-only contracts. Unlike .NET's nominal Delegate constraint, no delegate inheritance or invocation signature is implied. AOT/JIT function-kind method specialization is separately qualified by the native IL fixture. Raven method emission/import is qualified by the separate-provider Raven fixture.

Validation: NeoCLR.Metadata.Experimental.Tests --function-kind-constraint covers accepted signatures, rejected nominal/primitive arguments, forwarding, separate snapshots/imports, malformed metadata, introspection and CLI rejection. No guest API or RavenDoc input changes; this host SDK manual entry is its reference.

Native Function type tokens (2026-10-16)

MethodILGenerator.LoadTypeToken(SignatureType.Function(signature)) and Emit(OpCode.Ldtoken, ...) now preserve a complete structural function signature in native ldtoken metadata. Ordinary ownership/scope validation still applies; Void, borrowed and Self tokens remain rejected. CLI executable/reference export rejects these tokens with InvalidDataException rather than substituting nominal Func/Action identity. Other existing function transport remains unchanged. Focused function-kind SDK checks validate native token encoding/readback and CLI rejection.

Managed array-element addresses

OpCode.Ldelema is accepted by MethodBuilder.Emit(OpCode, SignatureType) and IILGenerator.Emit(OpCode, SignatureType). It consumes a vector reference followed by an Int32 index and produces a managed reference to the specified element type. The element type must be a valid, owned array storage signature; Void and invalid owners are rejected. Stack validation rejects mismatched array/element types. Runtime null and bounds checks apply before the address is used. An address may be consumed by typed loads/stores or value-type instance calls; it is not an unmanaged pointer and does not bypass the runtime's reference/lifetime rules.

CLI emission uses standard ldelema (0x8f plus element token); native emission uses the existing ldelema instruction. No runtime opcode or container version changes. This closes an authoring gap relative to .NET, with no deliberate semantic divergence. The enum member is appended to preserve existing values. The general typed Emit overload is the public entry point; no convenience method is added.

Validation: --array-address-integration runs the CLI array checks, verifies a native consumer and executes an Int32 array-address/store/read returning 42 in the interpreter. Wrong-element address authoring is rejected. Raven also exercises a nominal struct array in the interpreter. Native AOT allocation of nominal struct arrays remains unsupported; array-address authoring does not remove that allocation limitation.

Checked integer arithmetic

MethodBuilder.Emit(OpCode) and IILGenerator.Emit(OpCode) accept these additional operand-free codes:

Code Operation Overflow interpretation
Add_Ovf Addition Signed
Sub_Ovf Subtraction Signed
Mul_Ovf Multiplication Signed
Add_Ovf_Un Addition Unsigned
Sub_Ovf_Un Subtraction Unsigned
Mul_Ovf_Un Multiplication Unsigned

Each consumes two matching integer evaluation values and pushes one value of the same evaluation type. Supported categories are Int32, Int64, IntPtr and UIntPtr; UInt32/UInt64 signatures use the existing Int32/Int64 evaluation categories. The opcode determines signedness independently of the signature. Native width is the execution target's pointer width. Floating-point, Boolean, reference, empty and mismatched evaluation stacks are rejected with InvalidDataException when writing either CLI or native output. Normal numeric promotion/conversion must happen before these instructions. Subword values use their promoted evaluation width; this does not check subsequent narrowing to byte or short.

// In a method taking two Int32 arguments and returning Int32:
var il = method.GetILGenerator();
il.LoadArgument(0);
il.LoadArgument(1);
il.Emit(OpCode.Add_Ovf);
il.Return();

CLI uses the standard add.ovf, sub.ovf, mul.ovf and .un encodings. Native emission uses the existing instructions with those same spellings; no container or runtime opcode is added. Overflow throws OverflowException on .NET and reports the existing ArithmeticOverflow fault on NeoCLR. Native host fault status terminates the invocation without publishing a result; it does not throw a CLR exception across the host boundary.

This closes an SDK authoring gap relative to .NET checked addition and its unsigned form. Enum members are appended, preserving previous numeric values. There is no new convenience method or automatic checked context. Raven must still choose these operations during checked-expression lowering. Checked numeric conversion authoring and native lowering are described below.

See checked arithmetic validation for the compiled SDK consumer, rejection cases and execution-mode evidence.

Checked numeric conversions

The operand-free MethodBuilder.Emit(OpCode) and IILGenerator.Emit(OpCode) overloads accept the following appended enum members. Existing enum values are unchanged.

Signed-source opcode Unsigned-source opcode Destination
Conv_Ovf_I1 Conv_Ovf_I1_Un SByte
Conv_Ovf_U1 Conv_Ovf_U1_Un Byte
Conv_Ovf_I2 Conv_Ovf_I2_Un Int16
Conv_Ovf_U2 Conv_Ovf_U2_Un UInt16
Conv_Ovf_I4 Conv_Ovf_I4_Un Int32
Conv_Ovf_U4 Conv_Ovf_U4_Un UInt32
Conv_Ovf_I8 Conv_Ovf_I8_Un Int64
Conv_Ovf_U8 Conv_Ovf_U8_Un UInt64
Conv_Ovf_I Conv_Ovf_I_Un IntPtr
Conv_Ovf_U Conv_Ovf_U_Un UIntPtr

Each consumes one integer or floating evaluation value. Sources may have Int32, Int64, IntPtr, UIntPtr, Single or Double evaluation categories; unsigned fixed-width signatures already normalize to the matching integer category. The _Un suffix interprets integer source bits as unsigned, independently of signature signedness. Floating inputs truncate toward zero; NaN, infinities and unrepresentable truncated results overflow. Pointer-sized destinations use the execution target width.

Destinations of up to 32 bits produce Int32 stack values, 64-bit destinations produce Int64, and native destinations produce IntPtr/UIntPtr. Small signed results sign-extend. The conversion validates the destination range before that stack promotion. An empty stack or nonnumeric source rejects with InvalidDataException when writing CLI or native output; ordinary emission still defers flow validation. No array-length marker, reference, Boolean or managed pointer conversion is implied.

CLI uses standard conv.ovf.*[.un] instructions and OverflowException. Native emission uses the existing identically named operations and ArithmeticOverflow. The interpreter and shared native JIT/AOT lowering implement them. Native faults preserve the caller result slot and use the existing fault-state contract. Native qualification covers macOS ARM64; existing Windows profile restrictions remain.

For a method with an Int64 argument and Int32 result, for example:

var il = method.GetILGenerator();
il.LoadArgument(0);
il.Emit(OpCode.Conv_Ovf_I4);
il.Return();

Use RuntimeAssemblyContainer.WriteBinary(assemblyBuilder) for floating literal fixtures: that overload selects the existing schema needed for unsigned Double bits. See qualification and remaining work.

Static Self specialization helpers — development 2026-10-16

The unstable Rust host native_metadata module exposes two code-generation helpers:

  • validate_self_interface_bound(&Module, &Type, &Type) -> Result<(), Fault> requires closed types and complete linked metadata, exact nominal interface declaration, matching member signatures, and implementing-type Self conformance. It rejects symbolic arguments, missing metadata and structural lookalikes. Variance does not substitute for an exact declared bound.
  • resolve_static_self_call(&Module, &Type, &FunctionRef) -> Result<Function, Fault> resolves a closed static interface contract to its nominal concrete implementation without executing it. It uses the same conformance rules and rejects instance targets. Borrowed receiver adaptation is outside this helper's contract.

Callers must supply validated linked metadata and preserve its declaration identities; these are compiler services, not guest reflection or an unchecked invocation API. The code generator admits only nongeneric nominal interface method bounds in this slice, alongside existing function-kind bounds. Constructed interface bounds, instance Self adaptation and other generic method restrictions remain separate. These Rust-only functions have no RavenDoc guest type selection or CLI representation; this manual entry and Rustdoc are their API reference.

Symbol-authored method interface bounds — development 2026-10-16

AssemblyBuilder.CreateMethodReference adds the optional final parameter IReadOnlyList<GenericMethodTypeConstraint>? interfaceBounds = null. Bounds are copied, limited to 128, and admitted only on static generic methods. Each bound must name an output-owned nongeneric nominal interface via SignatureType.ImportedType, with a valid method parameter ordinal. Null entries, duplicates, foreign ownership, noninterface or constructed/generic bounds reject with ArgumentException. A reference with the same callable identity but a different bound sequence rejects with InvalidDataException rather than silently reusing an unconstrained contract.

ImportedMethodReference.MakeGenericInstance checks these declared bounds; open forwarding is checked when emitting the caller. Native emission retains the bound in the imported method contract; actual dependency identity, membership and member signatures are checked again by runtime linking/specialization. Creating a reference does not load or verify the dependency. Use the existing dependency hash/core identity contract and CompleteInterfaceReference workflow. No guest API or CLI bridge encoding is added. The validated use is a static class method with a nongeneric nominal interface bound and a separate-provider Complex consumer on interpreter/JIT/AOT. This SDK extension does not admit new structural constraint forms.

Int32 class constants

FieldDefinition(string name, ushort attributes, SignatureType fieldType, object? constant) now accepts Int32 literal fields on nominal class/value owners as well as enum members. Use Static | Literal | HasDefault (0x8050) plus Public (6), Assembly (3) or Private (1), and PrimitiveType.Int32. Attach through TypeDefinition.Fields. IsLiteral, Constant, signature, name and access survive CLI/native reads and reference projection. Literal fields allocate neither instance nor static storage. Duplicate names, invalid flags/types, interface owners and more than 256 literals are rejected. Other constant types and literal custom attributes remain unsupported. Native artifacts use the optional literal_fields metadata list; older runtimes reject that schema rather than silently ignoring it. Use the matching SDK/runtime.

Type initializers

  • TypeBuilder.AddTypeInitializer() -> MethodBuilder adds the unique private static parameterless .cctor with no result. Duplicate methods throw ArgumentException; intrinsic primitive/enum owners throw InvalidOperationException.
  • MethodBuilder.IsTypeInitializer distinguishes runtime initialization from instance .ctor construction. MethodDefinition(".cctor", 0x1811, signature) is the equivalent detached declaration; the signature must be nongeneric, parameterless and Void.
  • TypeDefinition.IsBeforeFieldInit reads the CLI timing flag on authored or loaded definitions. TypeDefinition.SetBeforeFieldInit(bool value = true) and TypeBuilder.SetBeforeFieldInit(bool value = true) select relaxed timing on an attached authored type; loaded/detached mutation throws InvalidOperationException. False is strict timing and the builder default. Native relaxed initialization uses first static-field access; strict triggers follow the runtime contract.
var state = assembly.AddClass("Example", "State");
var value = state.AddField("Value", PrimitiveType.Int32, FieldVisibility.Public,
    isReadOnly: true, isStatic: true);
var initializer = state.AddTypeInitializer();
initializer.LoadConstant(42);
initializer.StoreField(value);
initializer.Return();

Readonly static writes are legal only in the exact owning initializer, including its generic arguments. Calls, function bindings and entry-point selection cannot invoke .cctor directly; graph validation throws InvalidDataException. Native emission uses canonical owner..cctor and before_field_init, requiring matching runtime/SDK readers. CLI/native snapshots and reference projection preserve timing and readonly flags. Reference assemblies retain declarations, not executable bodies. Interface initializers are excluded from required implementation methods. Native storage/state remain invocation-owned; failed initialization retains the terminal Fault instead of a CLR exception wrapper. These host SDK APIs remain manually referenced here, outside the guest RavenDoc selection; no guest API snapshot changes.

Native field origin tokens

Native source field_tokens now contains instance fields, static storage and non-enum literal declarations, in that order. field_access and field_readonly continue to describe instance storage; static and literal declarations carry their own flags. Readers accept legacy instance-only token tables. Guest introspection reports no source token for a legacy static/literal declaration instead of inventing one. Metadata ordinals are separate from instance/static storage indices. SDK static field and class-constant roundtrip tests cover the emitted/projection contract.

Generic runtime-service references

AssemblyBuilder.CreateFunctionReference accepts an optional final bool isInternalCall = false argument. Pass true only when the selected native symbol has MethodImplAttributes.InternalCall; the emitted reference then retains the exact runtime service name rather than the generated ordinary-function name. A repeated reference with a conflicting flag is rejected. The existing dependency identity, snapshot digest, parameter scope and signature checks still apply.

Bodyless assembly-function internal calls may now have generic method parameters. SDK authoring, native reading, definition import and reference projection preserve those parameters. No host type erasure, runtime registration, dynamic library loading or new instruction is implied. The runtime independently validates the service name, exact signature and concrete type arguments; arbitrary generic services are not thereby implemented. Type-owned internal calls remain unsupported by this API.

The native queue-service probe exercises definition and symbol-authored references against production TaskQueue, replacing the two corresponding legacy seed declarations in the test dependency to avoid duplicate implementations. It does not replace the production service bundle or establish complete native core production.

Core Enum base classification

Model.TypeDefinition.IsValueType and Model.TypeBuilder.IsValueType exclude the source-owned core System.Enum base class. With matching output and core identities, a top-level System.Enum derived from the output's System.ValueType remains an ordinary abstract reference class, so SetAbstractClass() is valid. A same-named declaration in a different output does not receive this authoring exception. Ordinary enum declarations extending core System.Enum and structs extending System.ValueType remain value types.

The CLI projection reader also recognizes the local System.Enum base as a reference class; classification is not a replacement for runtime identity validation. Native metadata retains the explicit category. This matches the .NET Enum hierarchy. The focused --core-base-types metadata test covers authoring and both native and CLI projection roundtrips. No guest runtime API is added by this correction.

Native value-record ancestry (development, 2026-10-18)

void TypeBuilder.SetValueTypeBase(ImportedTypeReference baseType) binds the selected runtime's fieldless System.ValueType as the nominal base of an ordinary native value record. Call it before adding members. The reference must belong to the same builder, be nongeneric and top-level, and have a complete class-base contract with zero inherited instance fields. Native reading preserves the scoped base identity and value category. The runtime separately checks that this abstract foundation belongs to the host-selected Object module and derives directly from it.

Binding does not add reference storage, alter copy semantics or require a call to a reference-base constructor. ArgumentException rejects missing, foreign, non-ValueType or storage-bearing contracts; InvalidOperationException rejects reference/enum/primitive owners, repeated binding or binding after members exist; null raises ArgumentNullException. Existing class SetBaseType remains distinct. For an imported System.ValueType reference parent, register its resolved contract with CompleteClassBaseReference(parent, methods, 0), then call valueRecord.SetValueTypeBase(parent) before declaring fields and constructors.

This slice covers an external foundation for ordinary value records. Local-core, enum and intrinsic-primitive ancestry are not added by this API. The temporary CLI projection keeps its ordinary CLR ValueType base; native metadata records the exact imported foundation. Validation and three-mode consumer.

Native enum bases (development, 2026-10-18)

void TypeBuilder.SetEnumBase(ImportedTypeReference baseType) binds an enum to an owned, complete, nongeneric, top-level System.Enum contract with zero inherited fields. Register the contract with CompleteClassBaseReference(parent, methods, 0) then call enumeration.SetEnumBase(parent). Existing literals/value__ storage stay unchanged. Null raises ArgumentNullException; foreign, incomplete, wrong-name or storage-bearing contracts raise ArgumentException; non-enum owners or repeated binding raise InvalidOperationException. Native loading independently verifies Enum → ValueType → the selected Object foundation. This producer API is covered here outside guest RavenDoc selection; no guest signature changes.

Owned intrinsic and enum bases (development, 2026-10-18)

  • void TypeBuilder.SetValueTypeBase(TypeBuilder baseType) binds an intrinsic value primitive/grapheme to the same assembly's fieldless abstract ValueType over its native Object root. Call before members. Ordinary nonintrinsic records are outside this overload.
  • void TypeBuilder.SetEnumBase(TypeBuilder baseType) binds a core enum to the same assembly's fieldless abstract Enum over that ValueType/Object foundation. Existing enum literals and value__ storage are retained.

Both reject null (ArgumentNullException), foreign or malformed foundations (ArgumentException), unsupported owners or repeated binding (InvalidOperationException). Runtime loading validates the actual foundation identity. These native producer APIs are manually covered here outside guest RavenDoc selection. SetBaseType(ImportedTypeReference) additionally permits a closed reference root to bind the selected external Object, preserving all other ownership/member-order checks. Imported Object slot references retain virtual classification for exact inherited override validation.

Opaque memory-view metadata (development)

MemoryViewKind selects Slice, ReadOnlySlice, Memory or ReadOnlyMemory. TypeBuilder.SetMemoryView(kind) marks a canonical System generic value type with one type parameter and no fields, interfaces or constraints. An invalid enum throws ArgumentOutOfRangeException; incompatible names/shapes or a conflicting previous kind throw InvalidOperationException. A failed selection leaves the previous contract intact. Writing validates the final declaration again.

TypeDefinition.MemoryView and NominalTypeInfo.MemoryView expose the nullable contract on authored or imported declarations. Native serialization/import and imported method owners preserve it. CreateReferenceAssembly rejects assemblies containing these types: no CLI projection of an empty ordinary record is safe. Use RuntimeAssemblyContainer.WriteLibraryBinary for a native-only library. The interpreter owns the layout and enforces lifetimes; native JIT/AOT lowering is not established by this metadata support.

Symbol-only producers use AssemblyBuilder.SetMemoryView(importedType, kind) after reading the matching native type's explicit contract. It requires a canonical unconstructed System value definition owned by that builder; invalid shapes throw ArgumentException and conflicting contracts throw InvalidOperationException. Imported constructions and method owners keep the canonical runtime identity. This explicit contract is not inferred from a type's name alone.

Nominal method class bounds (2026-10-21 development)

MethodBuilder.AddBaseTypeConstraint(int parameterIndex, SignatureType bound) adds one nongeneric reference-class bound per method parameter. The bound must be an owned local nonstatic class or an output-owned imported class with registered nominal identity. Invalid ordinals, values/interfaces, generic bounds, foreign owners, duplicates, a second class bound and FunctionType combinations throw ArgumentException; null throws ArgumentNullException. Ordinary category flags and interface bounds remain separate and may coexist with a class bound.

MethodDefinition.TypeConstraints and introspection preserve the complete bound. The legacy interface-only query rejects known local class bounds. CLI uses ordinary GenericParamConstraint rows; native metadata uses the existing TypeBound shape. CLI/native readers, CLI reference projection and ordinary ImportReference retain nominal bounds; structural composition imports still require their explicit opt-in. The ordinary import now supports interface bounds too, replacing its earlier NotSupportedException for all bounded methods. Host-authored imported ancestry continues to require its explicit class-base facts.

Closed local derived and generic-derived types satisfy a nongeneric base bound; method and declaring-type forwarding must prove the required ancestry. Native specialization reuses runtime ancestry validation before removing parameters. Open or constructed class bounds are outside this increment. Existing class inheritance reference-projection limits remain; the projection test uses a root class while derived cases are checked through CLI/native execution metadata.

Validation: metadata tests --method-class-bounds, --method-categories, --function-kind-constraint, --structural-method-constraints; backend specialization tests; Raven's --method-category-import probe. No guest public signature or RavenDoc input changes in this increment.

Floating literal fields — development 2026-10-21

FieldDefinition's constant constructor and FieldDefinition/Introspection.FieldInfo Constant now accept/return boxed Int32, Single or Double values (object?). Callers previously using nullable-Int32 members must pattern-match or cast the returned value. Null means absent or unsupported. Literal flags remain Static|Literal|HasDefault; a mismatched floating width throws ArgumentException. Supported nominal owners and the Single/Double primitive owners can declare these storage-free constants. Enum literals remain Int32-backed.

CLI constants use the standard typed Constant table. Native literal_fields.value retains an Int32 number for existing literals and uses { "single_bits": "xxxxxxxx" } or { "double_bits": "xxxxxxxxxxxxxxxx" } for floats. Exact-width hexadecimal strings preserve infinities, signed zero and NaN payloads; malformed values reject. Native snapshots, CLI reference projection and Raven import retain types and bits. Use a matching runtime/compiler/metadata SDK; older readers reject these new shapes. Reflection getters and constant snapshots return the appropriate boxed primitive; reading a constant in source is inlined and needs no static storage or initialization.

Generic declaration tokens (development, 2026-10-21)

IILGenerator.LoadTypeDefinitionToken(SignatureType type) emits a runtime type handle for the generic declaration underlying an owned/imported nominal signature. It discards supplied generic arguments only for this explicit token operation; normal LoadTypeToken retains constructed arguments. Obtain the generator from MethodBuilder.GetILGenerator(). Nongeneric/structural arguments are rejected. The declaration must belong to the current assembly or an explicitly imported reference. Native metadata retains the declaration identity without introducing caller-scoped parameters; CLI output uses the ordinary TypeDef/TypeRef ldtoken. This does not permit generic definitions as local/field storage.

Native generic composition imports (2026-10-21)

The explicit ImportExperimentalCompositionReference path now accepts native static methods (including generic extension methods) as well as free functions. Generic class, value-type and interface wrappers retain composed arguments through the ordinary checked generic construction/substitution path. This repairs the HttpClientJsonExtensions.GetFromJson<T> import of Task<Result<T, HttpError | JsonError>>; the public HTTP API is unchanged. Default imports still reject compositions. Generic closure involving composed storage still requires EnableExperimentalCompositionStorage, and normal access, arity, constraints, nesting limits and provider identity checks remain in force. Instance composition-call import is not introduced by this change.

This is a native metadata SDK correction, with no CLI projection, Runtime Contract configuration or ABI change. The existing explicit Raven native backend owns selection of this import path; ordinary .NET compilation is unchanged. SDK composition-import and authored-composition tests pass, and the freshly compiled HTTP client/server pass interpreter end-to-end requests (including UTF-8 JSON and invalid input). Fresh packaged SDK/JIT qualification remains separate.

Development Character identity (2026-10-21)

Native grapheme owners and references now require System.Character, replacing System.Char in the native APIs described above. The serialized Char tag and runtime service names are unchanged implementation details. Rebuild all native consumers with the matching compiler/library; this is a development API migration. Ordinary CLI System.Char imports, including signed core scope and 0x03 encoding, remain UTF-16 code units. The focused metadata checks use a small separate CLI fixture so they do not depend on the full test runner's field count.

Nominal interface owner bounds (development)

GenericTypeConstraint and imported owner constraints admit one nongeneric nominal class or interface bound per parameter. An interface bound checks conformance for both values and references; it does not imply a reference-type constraint. The native reader/importer retains these bounds, and generic method calls can forward a compatible enclosing-owner bound. Native specialization validates the closed arguments before removing generic parameters from executable shapes.

The CLI projection uses GenericParamConstraint; native metadata uses its existing TypeBound form. This is the same nominal interface constraint model used by .NET, within the SDK's current single-bound and nongeneric-bound limits. It does not provide general structural-union constraint satisfaction. Synthesized Raven closure owners currently require owned nominal bounds; imported nominal closure bounds remain unsupported. See error diagnostics for the consumer.

Method inlining options (development, 2026-10-28)

MethodDefinition.SetImplementationFlags(System.Reflection.MethodImplAttributes flags) and MethodBuilder.SetImplementationFlags(System.Reflection.MethodImplAttributes flags) set an authored managed method's implementation flags. Accepted values are zero, NoInlining (8), AggressiveInlining (256), or both (264). NoInlining wins when combined. Zero restores automatic policy. The method returns void; unsupported bits throw ArgumentOutOfRangeException, and loaded methods, native imports or existing InternalCall declarations throw InvalidOperationException. Neither method creates an executable body.

Native serialization, import and CLI reference projection retain these flags. MethodInfo.GetMethodImplementationFlags() reports them without executing code. InternalCall remains a separate bodyless runtime-service contract. JIT and AOT share a bounded leaf inliner; aggressive hints do not override safety restrictions. The interpreter ignores inlining hints. See the contract and validation.

method.SetImplementationFlags(System.Reflection.MethodImplAttributes.NoInlining);

Generic parameter custom attributes (development, 2026-10-28)

Model.TypeDefinition.GetGenericParameterCustomAttributes(int position) and Model.MethodDefinition.GetGenericParameterCustomAttributes(int position) return IList<CustomAttributeDefinition> for a zero-based parameter ordinal. Authored collections are mutable (maximum 256 attributes per parameter); loaded collections are read-only. An ordinal outside GenericArity throws ArgumentOutOfRangeException. Attribute ownership and value validation follow ordinary custom attributes.

Introspection.GenericParameterTypeInfo.GetCustomAttributes() and Introspection.MethodGenericParameterTypeInfo.GetCustomAttributes() expose metadata-only views without running attribute constructors. CLI output uses GenericParam rows; native output uses optional origin.generic_parameter_tokens. Absent tokens preserve legacy compatibility. Invalid arity, duplicate identities, zero tokens and other token tables reject. CLI projection preserves owner/ordinal. The focused metadata test group is --generic-attributes.

Function-dependent signatures (development, 2026-10-30)

MethodSignature.FunctionType: SignatureType is the authoritative signature view. FromFunctionType(type, genericParameterNames) accepts a structural function or a scoped generic parameter; the latter must have the function constraint on its owner. IsDependent identifies an unresolved whole signature. Parameter/result queries on that shape throw InvalidOperationException until substitution resolves it. InteropFunction(functionType, objectType, genericParameterNames) declares a boxed array body ABI; InteropObjectType exposes that transport marker. It is not the public method signature. NoResult distinguishes no stack result from inhabited unit.

SignatureType.FunctionReturn(functionType) projects a known result or retains an open type/method parameter operand in FunctionReturnOperand. Other operands are rejected with ArgumentException; scoped function constraints are required. Substitution traverses projections, including ordinary generic method results.

Introspection.MethodInfo.FunctionType: TypeInfo returns a FunctionTypeInfo or a function-constrained parameter view. Closed methods expose ordinary parameters and results. FunctionTypeInfo.ParameterModes preserves value/ref/out signature modes. FunctionReturnTypeInfo.FunctionType identifies the operand of an unresolved result projection; resolved projections expose the ordinary result TypeInfo.

Native format 6 stores function_type, optional boxed_arguments, and FunctionReturn type expressions. Format 5 remains readable. Positional parameter metadata cannot contradict a whole-signature reference. CLI executable emission and neoIL text export of these new forms are not supported; use the native metadata writer. These host SDK APIs are documented here rather than included in the guest RavenDoc selection.

Parameter defaults (development)

ParameterDefaultValue(object? value) accepts bool, signed/unsigned integer, float, double, string and explicit null constants. Other values throw ArgumentException. Value returns the immutable value. MethodDefinition.ParameterDefaults is a read- only position-to-default map excluding the receiver. SetParameterDefault(position, value) (also on MethodBuilder) sets or clears a default on authored definitions; null clears, new ParameterDefaultValue(null) stores explicit null for references or zero initialization for a nominal value-type parameter. No constructor runs. Invalid position throws ArgumentOutOfRangeException; incompatible types throw InvalidDataException; loaded definitions reject mutation with InvalidOperationException.

ParameterInfo.HasDefaultValue distinguishes absence from explicit null; DefaultValue returns the constant or null. Native and CLI snapshots preserve these values. CLI projection uses Param flags and Constant rows. See the native default contract for supported kinds, typed null/default semantics, validation and remaining gaps.