Native module contract

Documentation status: reference — see Maturity and evidence.

Boundary

A native ABI module is a dynamic library that exposes one well-known function returning a versioned function table. The host does not discover arbitrary exported implementation methods. It loads the table, validates it, initializes the module, and then performs all ABI calls through that table.

dynamic library
  -> GetModuleAPI
  -> versioned API table
       init
       shutdown
       invoke
       release
       free
       get-last-error

The function names above describe the public roles of the entries; application SDKs should not expose this low-level table directly.

Validation before use

The current loader validates all of the following before the module is considered usable:

1. the library exists and can be loaded;
2. the module exports the expected API-table entry point;
3. the entry point returns a non-null table;
4. the ABI version matches the host ABI version;
5. the table is at least as large as the host expects;
6. every mandatory function pointer is present;
7. module initialization succeeds.

A failure in any of these steps prevents publication of a usable module instance.

Initialization and shutdown

Initialization receives an opaque host-context pointer. The ABI intentionally does not prescribe the internal structure of that context in the generic module contract.

Shutdown belongs to the module lifecycle. The host unloads the dynamic library only after shutdown has been attempted and the API table is no longer used.

Invocation

The generic native function receives:

receiver handle
method id
argument-record pointer
result-storage pointer

A constructor or static call normally has no receiver. An instance call carries the opaque handle returned by a previous operation. The method descriptor determines whether a receiver is required, and the host rejects a mismatch before entering the module.

Result codes and last error

0 denotes success in the current ABI contract. Failures return a non-zero result code. The host may then ask the module for its last UTF-8 error message.

The returned message buffer is module-managed memory, so the host copies the text and returns the buffer through the module's free function. This is a concrete example of why allocation and release must remain on the same ABI side.

Handles

A module handle is opaque. The only portable operations are those published by the ABI. In particular, a client must not:

• dereference the handle;
• assume it points to a stable native object layout;
• compare addresses as business identity;
• free it with the host allocator.

When ownership says the caller owns the returned handle, release it through the module release entry.

Current portability note

The current native loader implementation that was inspected uses the Windows dynamic-library path. The ABI table itself is platform-neutral in shape, but this page does not claim that every host loader implementation is already certified on every operating system.