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

FormatKind::SyscallPayload

Magic

0x4D53_5350 (ASCII MSSP)

Current version

1

Supported range

[1, 1]

Registry

mudu/src/compat/mod.rs

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 mgen and is project-controlled, not the default rmp_serde derive output.

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 [tag,payload], the result envelope [0,v]/[1,e], and frame-level checks are unchanged. The version number was not bumped: there was no deployed external ecosystem at revision time and every MPK was rebuilt with the revision; the version mechanism is reserved for future genuine cross-version scenarios (see Upgrade and rollback rules).

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.

Current syscall kinds#

Kind

WIT function

1

query

2

command

3

batch

4

open-session

5

close-session

6

get

7

put

8

delete

9

range

10

fs-open

11

fs-close

12

fs-read

13

fs-write

14

fs-pread

15

fs-pwrite

16

fs-lseek

17

fs-fstat

18

fs-stat

19

fs-fsync

20

fs-readdir

21

relation-get

22

relation-update

23

relation-insert

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

uni-data-type.wit

UniDataType

uni-data-value.wit

UniDataValue / UniDataValueField

uni-scalar.wit

UniScalar

uni-scalar-value.wit

UniScalarValue

uni-record-type.wit

UniRecordType / UniRecordField / UniFieldAttr

uni-result-type.wit

UniResultType

uni-result-set.wit

UniResultSet

uni-tuple-row.wit

UniTupleRow

uni-sql-stmt.wit

UniSqlStmt

uni-sql-param.wit

UniSqlParam

uni-query-argv.wit

UniQueryArgv

uni-command-argv.wit

UniCommandArgv

uni-command-result.wit

UniCommandResult / UniCommandReturn

uni-query-result.wit

UniQueryResult / UniQueryReturn

uni-error.wit

UniError

uni-oid.wit

UniOid

uni-fs-open-argv.wit

UniFsOpenArgv

uni-fs-stat.wit

UniFsStat

uni-fs-dirent.wit

UniFsDirent

uni-syscall.wit

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

record

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.

variant

Two-element MessagePack array [tag, payload]. tag is a u32 discriminator assigned by declaration order (starting at 0). If a case has no payload, payload is a dummy 0u8 so the array always has length 2.

enum

Bare u32 discriminant, assigned by declaration order (starting at 0).

list<T>

MessagePack array of encoded T.

option<T>

MessagePack nil for none; otherwise the encoded T for some.

result<T, E>

MessagePack array [ok_tag, value] where ok_tag is 0u8 for ok and 1u8 for err, followed by the encoded T or E.

string

MessagePack str.

list<u8> / blob

MessagePack bin at the func level; a MessagePack integer array in the record context (this is why UniError.err_details and UniResultSet.cursor are arrays).

Primitive scalars (u8, i32, u64, f32, bool, char, …)

Standard MessagePack integer/float/bool/str representations.

box<T>

Same encoding as T; the box is transparent on the wire.

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

Bool

bool

1

U8

u8

2

I8

s8

3

U16

u16

4

I16

s16

5

U32

u32

6

I32

s32

7

U64

u64

8

U128

list<u8> (16 bytes, big-endian)

9

I64

s64

10

I128

list<u8> (16 bytes, big-endian)

11

F32

f32

12

F64

f64

13

Char

char (MessagePack str of one Unicode scalar)

14

String

string

15

Blob

list<u8> (MessagePack bin)

16

Numeric

string

17

Date

string

18

Time

string

19

Timestamp

string

20

TimestampTz

string

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

Scalar

UniScalarValue

1

Array

list<UniDataValue>

2

Record

list<UniDataValueField>

3

Binary

list<u8> (MessagePack bin)

A UniDataValueField is a record of {1: field_name: string, 2: field_value: UniDataValue}.

UniDataType — variant tags:

Tag

Variant

Payload

0

Scalar

UniScalar

1

Array

UniDataType

2

Record

UniRecordType

3

Option

UniDataType

4

Tuple

list<UniDataType>

5

Result

UniResultType

6

Identifier

string

7

Binary

0u8 dummy (variant case has no inner type)

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

Bool

11

F32

1

U8

12

F64

2

I8

13

Char

3

U16

14

String

4

I16

15

Blob

5

U32

16

Numeric

6

I32

17

Date

7

U64

18

Time

8

U128

19

Timestamp

9

I64

20

TimestampTz

10

I128

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) or err(UniError).

  • UniQueryReturn — variant: ok(UniQueryResult) or err(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 to ErrorCode::UnsupportedFormatVersion.

  • Flags check: decoders reject any non-zero flags value.

  • Message-kind validation: decoders reject unknown/0 message_kind values.

  • 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: string fields 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 version and 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 bump version and 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:

  1. All guest bindings (Rust, C#, AssemblyScript, Python) emit and accept the successor encoding version (v2).

  2. The new version has been the default for at least one release cycle.

  3. 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.rs

  • WIT schema source: mudu_binding/wit/

  • Syscall function interface: mudu_binding/wit/uni-syscall.wit

  • Host framed codec (authoritative): mudu_binding/src/codec/syscall_payload/

  • mgen Rust templates: mudu_gen/templates/rust/

  • mgen C# templates: mudu_gen/templates/csharp/

  • universal type family (Rust): mudu_binding/src/universal/

  • Legacy hand-written KV codec: mudu_binding/src/codec/handle_sys_session.rs

  • SQL request/response codec: mudu_binding/src/codec/handle_sys_incoming.rs, handle_sys_outcoming.rs

  • Host syscall entry points: runtime_wasm/src/interface/kernel_sync.rs, kernel_async.rs

  • Integration guide: doc/en/abi/guest_host_abi.md