MuduDB Format and Protocol Contracts

MuduDB Format and Protocol Contracts#

This directory contains the formal, versioned contracts for MuduDB’s persistent formats, network protocols, and deployment artifacts. Each contract is the source of truth for layout, versioning, compatibility, upgrade rules, and deprecation policy.

Active contracts#

Contract

Version

Status

Implementation

Page Header

v1

Stable

storage/src/page/format/latest.rs

Tuple Binary Format

v1

Stable

mudu_contract/src/tuple/tuple_binary.rs

Log Frame (WAL/XL/PL)

v1

Stable

wal/src/format/latest.rs

TCP Protocol Frame

v1

Stable

mudu_contract/src/protocol/format/latest.rs

MPK Package Manifest

v1

Stable

runtime_wasm/src/service/app_package.rs

Server Configuration

v1

Stable

mudu_runtime/src/backend/mudud_cfg/mod.rs

File Layout

v1

Stable

storage/src/time_series/time_series_file.rs

Guest→Host Syscall Payload

v1

Stable

mudu_binding/src/codec/syscall_payload/ (host router; registry in mudu/src/compat/mod.rs)

Adding or changing a contract#

  1. Propose the change in a dedicated PR.

  2. Update the relevant contract document in both en/ and cn/.

  3. Update the compatibility matrix, upgrade rules, and deprecation policy.

  4. Add or update golden fixtures in testing/fixtures/golden/.

  5. Add compatibility and corruption tests.

  6. Ensure CI passes before merging.

See How to Add a Format Upgrade for the detailed workflow.