Host ABI: raw imports, MessagePack codec, status code conventions, host_set_result/host_alloc

[tayebmokni]

Summary

Define and enforce the host ABI calling convention. Module name host. Function names snake_case verbs grouped by capability. All complex data crossing the boundary is length-prefixed bytes in linear memory, MessagePack-encoded. Status codes returned as i64: low 32 bits = status, high 32 bits = result length hint. Negative status codes for errors.

Design reference

• docs/02-plugin-system.md §4.3, §4.4, Appendix A (full ABI reference)

Acceptance criteria

• host module registered via runtime.NewHostModuleBuilder("host")
• host_set_result(ptr, len) records the guest-side result address (per-instance state)
• host_alloc(len) -> ptr calls back into the guest-exported allocator (plugin_alloc); host never directly allocates in guest memory without going through this path
• host_log(level, ptr, len) always available, no capability gate
• All msgpack codec helpers (packMsgpack, unpackMsgpack) in a shared host package; choice of library is vmihailenco/msgpack/v5
• Status code constants: 0 success, -1 no_cap, -2 quota_exceeded, -3 bad_input, -4 host_internal, -5 not_found, plus reserved ranges
• Each host function: reads args from guest memory at (ptr,len), validates capability token, executes, packs result, writes via host_set_result, returns combined status|len<<32
• Host module is shared (one instance per runtime) — per-call state (LastResultPtr, capsToken) is tracked per-Instance, not on the host module
• Tests: trivial round-trip plugin that calls host_log and a stub host function; assert msgpack encoded payload received intact
• Documentation: ABI v1 frozen and recorded; future ABI versions are additive

Dependencies

#6 (host scaffolding), #9 (instance pool)

Complexity

M

[tayebmokni]

Closing as DONE — implementation landed across the 280+ PRs shipped to date. See triage-report.md (2026-05-25 backlog audit) for the specific file/package evidence. Re-open with a specific gap if any acceptance criterion is missed.