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	mudu_kernel/src/storage/page/format/latest.rs
Tuple Binary Format	v1	Stable	mudu_contract/src/tuple/tuple_binary.rs
Log Frame (WAL/XL/PL)	v1	Stable	mudu_kernel/src/wal/format/latest.rs
TCP Protocol Frame	v1	Stable	mudu_contract/src/protocol/format/latest.rs
MPK Package Manifest	v1	Stable	mudu_runtime/src/service/app_package.rs
Server Configuration	v1	Stable	mudu_runtime/src/backend/mudud_cfg.rs
File Layout	v1	Stable	mudu_kernel/src/storage/time_series/time_series_file.rs
Guest→Host Syscall Payload	v1	Draft	mudu/src/compat/mod.rs (registry; codec pending Phase 2)

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.