Guest→Host Syscall Payload Contract v1#
Scope#
This document specifies the project-owned binary wire format used for MuduDB guest→host syscalls.
The wire format keeps the 16-byte header introduced in Phase 1 and encodes the
message body with MessagePack. The MessagePack layout is project-controlled:
it is derived from the canonical WIT definitions in
mudu_binding/wit/ and generated by mgen into
custom serde implementations for Rust and custom MessagePack formatters for C#.
The implementation uses rmp_serde (or an equivalent MessagePack runtime on the
C#/AssemblyScript/Python side) only as the low-level encoder/decoder; it does not
use the default rmp_serde derive behavior, which would serialize Rust enum
variants as maps or strings and would not be stable across guest languages.
The canonical syscall boundary is the WIT function interface declared in
uni-syscall.wit. The header and
MessagePack body described here are the runtime’s internal serialization of
those WIT function calls; guest code should call the WIT functions directly and
let the generated bindings handle the wire format.
The logical data model is the existing mudu_binding::universal type family;
this contract defines the wire encoding of those types.
Status: implemented and stable. All 23 message kinds are encoded and
decoded by the host router in
mudu_binding/src/codec/syscall_payload/
and dispatched in runtime_wasm (kernel_sync / kernel_async). Guest-side
implementations exist for workspace Rust guests, the standalone Rust SDK, the
C# SDK, AssemblyScript, and Python.
The obsolete UniDatTypeId / UniMuTypeFamily enumerations are not part of
this contract and have been removed from the binding layer. When a type-family
value needs to cross the boundary, it is carried inside UniDataType /
UniScalar instead.
Registry#
Property |
Value |
|---|---|
Format family |
|
Magic |
|
Current version |
|
Supported range |
|
Registry |
|
The runtime decodes only the current version. An unsupported version fails fast
with ErrorCode::UnsupportedFormatVersion. When the format version changes, MPK
packages are rebuilt for the matching runtime; the runtime does not retain
legacy decoders.
The same version is pinned into every MPK package: package.manifest.json
carries a syscall_abi_version: u32 field. The package writer (mpm_build)
always emits SYSCALL_PAYLOAD_CURRENT_VERSION (1); the loader in
runtime_wasm/src/service/app_package.rs
defaults a missing field to 1 and rejects any mismatch with
ErrorCode::UnsupportedFormatVersion. FormatKind::SyscallPayload is
registered in the global CompatibilityRouter (mudu_kernel/src/compat.rs)
with an identity v1 migration handler in
mudu_binding/src/codec/syscall_payload/migrate/;
migrate units are complete frames (16-byte header included).
Version history#
Version |
Date |
Summary |
|---|---|---|
1 |
2026-07-01 |
16-byte header (magic, version, flags, message kind) plus a MessagePack body. The MessagePack layout is generated from WIT by |
1 (in-place revision) |
2026-09-11 |
Record/request bodies changed from positional arrays to integer-keyed MessagePack maps (field/parameter numbers = 1-based WIT declaration order, protobuf-style); decoding made lenient (any integer width accepted, unknown map keys skipped, missing fields defaulted — proto3 semantics). Variant |
Payload layout#
Every syscall request and every syscall response is encoded as a single self-describing message:
+--------------------------------+
| Header (16 bytes) |
+--------------------------------+
| Body (variable, MessagePack) |
+--------------------------------+
There is no separate length prefix outside the header; the WIT transport delivers the exact byte range.
Header#
All header fields are big-endian.
Offset |
Size |
Field |
Description |
|---|---|---|---|
0 |
4 |
|
Magic |
4 |
4 |
|
Payload format version. Current value: |
8 |
4 |
|
Reserved. Must be |
12 |
4 |
|
Message-kind discriminant. Still present in the wire header for routing, but the set of valid kinds is defined by |
version is the payload format version, not the WIT interface version. It
increments only when the encoding rules themselves change — for example
integer semantics, the header layout, or the map/array structural rules.
Schema evolution (appended fields, appended message_kinds, appended variant
tags) is absorbed in-version by the field-number mechanism and does not bump
version.
The WIT function interface in uni-syscall.wit is the authoritative definition
of which syscalls exist and what their request/response types are. The runtime
maps each WIT function to the same internal header + MessagePack path; the
message_kind discriminant is therefore an implementation detail retained for
runtime routing.
Current syscall kinds#
Kind |
WIT function |
|---|---|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
Body encoding#
The body is a single MessagePack value. The exact byte sequence is controlled by
the mgen templates and must not be inferred from generic rmp_serde defaults.
Source of truth#
The canonical schema is the set of WIT files under
mudu_binding/wit/:
WIT file |
Rust generated type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
syscall function interface |
mgen reads these WIT files and emits language-specific source files. For Rust
it uses the templates in
mudu_gen/templates/rust/; for C# it uses
mudu_gen/templates/csharp/.
MessagePack encoding rules#
The generated code obeys the following rules, which override any default
rmp_serde behavior:
WIT construct |
MessagePack encoding |
|---|---|
|
MessagePack map keyed by the 1-based field numbers (declaration order); values are the encoded fields. Encoding writes all fields in ascending key order. |
WIT func parameter list |
Same as a record: a MessagePack map keyed by the 1-based parameter numbers. |
|
Two-element MessagePack array |
|
Bare |
|
MessagePack array of encoded |
|
MessagePack nil for |
|
MessagePack array |
|
MessagePack str. |
|
MessagePack bin at the func level; a MessagePack integer array in the record context (this is why |
Primitive scalars ( |
Standard MessagePack integer/float/bool/str representations. |
|
Same encoding as |
All body values go through one hand-written generic runtime per language
(on Rust, mudu_binding::universal::mp_wire): it encodes canonically exactly
like rmp_serde 1.3.1 (minimal-width integers, str8/bin8 thresholds) and
decodes leniently — integers of any MessagePack width are accepted (with a
range check on narrowing), unknown map keys are skipped, missing fields
decode to the type default (proto3 semantics) and map key order is free.
Structure stays strict: a record/request body must be a map, tuple lengths
are exact and unknown variant tags are rejected. The C#, AssemblyScript, and
Python sides generate equivalent runtime code from the same WIT.
OID / UniOid#
OID is the logical 128-bit object identifier (mudu::common::id::OID). On
the wire it is encoded as a record with two u64 fields, the MessagePack
map {1: h, 2: l}. Decoders reconstruct the logical
OID as ((h as u128) << 64) | (l as u128).
Variant tag tables#
The tags below are derived from the WIT declarations in
mudu_binding/wit/. They are listed here for
convenience, but the WIT files remain the canonical source.
UniScalarValue — variant tags:
Tag |
Variant |
Payload |
|---|---|---|
0 |
|
|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
Note: the WIT uni-scalar-value defines blob for binary scalar payloads;
UniScalarValue::Blob carries a Vec<u8>. U128 / I128 use 16-byte
big-endian byte arrays to stay portable across guest languages that lack a
native 128-bit integer MessagePack type.
UniDataValue — variant tags:
Tag |
Variant |
Payload |
|---|---|---|
0 |
|
|
1 |
|
|
2 |
|
|
3 |
|
|
A UniDataValueField is a record of {1: field_name: string, 2: field_value: UniDataValue}.
UniDataType — variant tags:
Tag |
Variant |
Payload |
|---|---|---|
0 |
|
|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
|
|
6 |
|
|
7 |
|
|
Note: box<T> is not a standalone variant. It appears only as a WIT
syntax sugar for recursive types (array, option) and is transparent on the
wire.
UniScalar — WIT enum, bare u32 discriminant:
Value |
Name |
Value |
Name |
|
|---|---|---|---|---|
0 |
|
11 |
|
|
1 |
|
12 |
|
|
2 |
|
13 |
|
|
3 |
|
14 |
|
|
4 |
|
15 |
|
|
5 |
|
16 |
|
|
6 |
|
17 |
|
|
7 |
|
18 |
|
|
8 |
|
19 |
|
|
9 |
|
20 |
|
|
10 |
|
UniScalar and UniScalarValue now share the same tag numbering.
Composite type layouts#
The MessagePack encoding of each record/variant follows the generic rules above. For reference, the field numbers and payload shapes are (record keys are the 1-based field numbers in declaration order):
UniOid—{1: h: u64, 2: l: u64}.UniSqlStmt—{1: sql_string: string}.UniSqlParam—{1: params: list<UniDataValue>, 2: param_names: option<list<string>>}.UniTupleRow—{1: fields: list<UniDataValue>}.UniFieldAttr—{1: attr_name: string, 2: attr_value: string}.UniRecordField—{1: field_name: string, 2: field_type: UniDataType, 3: field_attrs: list<UniFieldAttr>}.UniRecordType—{1: record_name: string, 2: record_fields: list<UniRecordField>}.UniResultType—{1: ok: option<UniDataType>, 2: err: option<UniDataType>}.UniResultSet—{1: eof: bool, 2: row_set: list<UniTupleRow>, 3: cursor: list<u8>}.UniError—{1: err_code: u32, 2: err_msg: string, 3: err_src: string, 4: err_loc: string, 5: err_details: list<u8>}.UniQueryArgv—{1: oid: UniOid, 2: query: UniSqlStmt, 3: param_list: UniSqlParam, 4: param_desc: option<UniRecordType>}.UniCommandArgv—{1: oid: UniOid, 2: command: UniSqlStmt, 3: param_list: UniSqlParam, 4: param_desc: option<UniRecordType>}.UniQueryResult—{1: tuple_desc: UniRecordType, 2: result_set: UniResultSet}.UniCommandResult—{1: affected_rows: u64}.UniCommandReturn— variant:ok(UniCommandResult)orerr(UniError).UniQueryReturn— variant:ok(UniQueryResult)orerr(UniError).UniSessionOpenArgv— currently a hand-written Rust record; its wire shape is{1: worker_id: UniOid}. It does not yet have a dedicated WIT file; if it is moved into WIT in the future it will follow the same encoding rules as above.
Relationship to the legacy session codec#
All 23 kinds — including the KV syscalls (Open…Range) — are now encoded
and decoded through the framed MessagePack path in
mudu_binding/src/codec/syscall_payload/,
wrapping each payload in the 16-byte header and using the project-controlled
MessagePack Result<T, E> encoding for errors instead of the legacy MERR
magic escape. The earlier hand-written binary session codec in
handle_sys_session.rs followed conventions matching this contract’s
primitives; the Phase 2 unification onto the project-controlled MessagePack
path is complete.
Integrity mechanisms#
Magic check: decoders reject messages whose magic is not
0x4D53_5350.Version check: decoders reject any version outside
[1, 1], mapping toErrorCode::UnsupportedFormatVersion.Flags check: decoders reject any non-zero
flagsvalue.Message-kind validation: decoders reject unknown/
0message_kindvalues.Length checks: decoders require at least 16 bytes for the header.
MessagePack structural validation: decoders reject malformed MessagePack payloads, trailing bytes after the body, unknown variant tags, and record/request bodies that are not maps. Decoding inside a map is lenient (unknown keys skipped, missing fields defaulted, any integer width), but narrowing overflow and type mismatches are still rejected.
UTF-8 validation:
stringfields must be valid UTF-8.
Structural body decode failures map to ErrorCode::Decode. Magic mismatches map
to ErrorCode::CorruptedData via the compatibility registry.
Compatibility matrix#
Reader \ Writer |
v1 |
|---|---|
v1 |
Compatible |
Only version 1 is supported.
Upgrade and rollback rules#
Two kinds of change are distinguished first:
Encoding-rule changes (integer semantics, header layout, the map/array structural rules, etc.) — bump
versionand follow the upgrade flow below.Schema evolution (appended fields/parameters, appended
message_kinds, appended variant tags) — absorbed in-version by the field-number mechanism; does not bumpversionand does not require rebuilding deployed MPKs: old and new packages keep interoperating through lenient decoding (unknown keys skipped, missing fields defaulted). Only guests that want to use a new field regenerate their bindings and repackage.
Rules:
Upgrade (encoding-rule change): A future v2 changes the header
version. When v2 is introduced, MPK packages are rebuilt for the matching runtime and offline migration handlers convert stored fixtures/test data.No legacy decoders: the runtime decodes only the current version. A message with an unsupported version fails fast with
ErrorCode::UnsupportedFormatVersion.No cross-encoding-version MPK support: packages are rebuilt per ABI version bump; versioning exists to make future encoding-rule upgrades explicit and controllable, not to preserve cross-version compatibility.
Deprecation policy#
Version 1 may be deprecated only after:
All guest bindings (Rust, C#, AssemblyScript, Python) emit and accept the successor encoding version (v2).
The new version has been the default for at least one release cycle.
MPK packages have been rebuilt against the new runtime.
Deprecation applies to encoding versions; in-version schema evolution (field-number appends) produces no deprecatable old version.
References#
Registry:
mudu/src/compat/mod.rsWIT schema source:
mudu_binding/wit/Syscall function interface:
mudu_binding/wit/uni-syscall.witHost framed codec (authoritative):
mudu_binding/src/codec/syscall_payload/mgenRust templates:mudu_gen/templates/rust/mgenC# templates:mudu_gen/templates/csharp/universaltype family (Rust):mudu_binding/src/universal/Legacy hand-written KV codec:
mudu_binding/src/codec/handle_sys_session.rsSQL request/response codec:
mudu_binding/src/codec/handle_sys_incoming.rs,handle_sys_outcoming.rsHost syscall entry points:
runtime_wasm/src/interface/kernel_sync.rs,kernel_async.rsIntegration guide:
doc/en/abi/guest_host_abi.md