Module host_abi 

Host ABI — the public on-the-wire memory format between the HOMECORE host and every WASM plugin.

Overview

HOMECORE uses JSON over UTF-8 linear memory for all host↔guest data. This matches HA’s JSON-everywhere convention and makes call payloads inspectable in debuggers without a schema file. Each hc_* host function and each guest export uses the same pointer + length convention:

  host calls alloc(size) → ptr  (exported by guest)
  host writes UTF-8 bytes into guest linear memory at [ptr, ptr+size)
  host calls the guest export with (ptr: i32, len: i32)
  guest reads and JSON-decodes the slice
  guest writes its reply via hc_state_set / hc_log / etc. (host imports)
  host calls dealloc(ptr, size) when finished   (exported by guest)

Wire types

Call	Direction	JSON schema
hc_state_get reply	host → caller	{"entity_id":"…","state":"…","attributes":{…}} or null bytes (not found)
hc_state_set args	guest → host	(entity_id, state, attrs) as 3 separate ptr/len pairs; each is a UTF-8 string or JSON object
hc_log args	guest → host	(level: i32, msg) where level 0=debug 1=info 2=warn 3=error
hc_state_subscribe	guest → host	entity_id UTF-8 string
setup_entry	host → guest	{"entry_id":"…","domain":"…","data":{}} (ConfigEntry JSON)
receive_event	host → guest	{"event_type":"state_changed","entity_id":"…","new_state":"…"}

Memory layout guarantees

• Buffers are always valid UTF-8 (JSON subset).
• Maximum buffer size is 64 KiB (65,536 bytes). Larger payloads must be split by the caller; the host rejects oversized writes with a WASM trap. This bound is enforced in [write_guest_buf].
• The host never holds a guest memory pointer across a WASM call boundary. Pointers are only valid for the duration of a single call.

hc_state_subscribe semantics

A plugin calls hc_state_subscribe(eid_ptr, eid_len) once per entity it wants to track. Subsequent state changes for that entity arrive via a receive_event call with event_type "state_changed".

Subscriptions are held for the lifetime of the plugin instance.

Structs

ConfigEntryJson

JSON payload passed to setup_entry when a config entry is set up.

StateChangedEventJson

JSON payload for receive_event — state_changed variant.

Enums

LogLevel

Log levels for hc_log.

Constants

MAX_ABI_BUFFER_BYTES

Maximum number of bytes the host will write into a single guest buffer. Plugins may safely size their alloc buffers at this ceiling.