docs: add project specification with CoT structure and XML to docs/source/design/

[Copilot]

Adds docs/source/design/project-spec.md capturing the architectural ground truth of the Mooncake codebase in English for onboarding, tooling, and AI-assisted development contexts. The document is placed under docs/source/design/ consistent with the repository's existing Sphinx documentation conventions, and is indexed in docs/source/index.md under the Design Documents section.

The document is structured using a Chain of Thought (CoT) preamble followed by XML-tagged sections where structured, machine-readable representation improves efficiency.

Description

CoT Preamble (<cot>)

• <understanding> — concise summary of the project and what the spec aims to capture
• <conflicts> — 3 spec tensions identified and resolved with explicit <resolution> tags:
  • C1: Dual Transfer Engine — stable TE vs. next-gen TENT (behind USE_TENT=OFF by default)
  • C2: PyPI package named mooncake-transfer-engine but covers the full platform, not just the Transfer Engine
  • C3: Two store access paths — coro_rpc (HA-protected via etcd) vs. REST proxy (no HA guarantees)
• <analysis> — 5 numbered reasoning steps from dependency discovery → API extraction → style rules

XML-structured Sections

XML element	Content
<dependencies>	Versioned libraries grouped by C++/Python/DevTools with version, source, and role attributes
<architecture>	Layered component hierarchy (<layer> → <component>)
<transports>	Plugin registry with protocols and hardware attributes (13+ transports)
<dataflow>	Step-by-step data flows with actor, call, input, output attributes (4 paths)
<api>	Metadata wrappers around C++/Python code blocks
<style> / <constraints>	Enforced style rules and mandatory constraints
<build-options> / <ci>	CMake build flags and CI matrix

Fenced code blocks are retained for actual C++/Python/bash syntax. Simple 2-column lookups remain as Markdown tables.

Spec Contents

• Tech stack — languages (C++20, Python ≥3.8, CUDA, Go 1.23.8), versioned dependencies (yalantinglibs 0.5.7, etcd v3.6.1, pybind11, ASIO, ruff 0.6.9, etc.)
• Architecture — layered monorepo (Foundation → Transfer → Storage → Compute → Integration), transport plugin pattern (13+ backends registered via installTransport()), master/replica KVCache store over coro_rpc
• Data flow — disaggregated prefill/decode path, KVCache Put/Get path, Python→C++ binding path
• API contracts — full TransferEngine public interface, MasterClient (tl::expected[T, ErrorCode] return convention), vLLM v1 MooncakeConnector scheduler/worker methods, CLI entry points, HandShakeRequestType enum
• Coding style & constraints — Google clang-format (4-space, 80-col), ruff, naming conventions (PascalCase types / camelCase methods / snake_case_ members), mandatory error handling, RAII ownership, thread-safety documentation requirement, memory registration rules

Files Changed

• docs/source/design/project-spec.md — new comprehensive project specification
• docs/source/index.md — added design/project-spec entry to the Sphinx toctree under Design Documents

Module

• Transfer Engine (mooncake-transfer-engine)
• Mooncake Store (mooncake-store)
• Mooncake EP (mooncake-ep)
• Integration (mooncake-integration)
• P2P Store (mooncake-p2p-store)
• Python Wheel (mooncake-wheel)
• PyTorch Backend (mooncake-pg)
• Mooncake RL (mooncake-rl)
• CI/CD
• Docs
• Other

Type of Change

• Bug fix
• New feature
• Refactor
• Breaking change
• Documentation update
• Other

How Has This Been Tested?

Documentation-only change; no runtime behavior affected.

Checklist

• I have performed a self-review of my own code.
• I have formatted my own code using ./scripts/code_format.sh before submitting.
• I have updated the documentation.
• I have added tests to prove my changes are effective.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[stmatengss]

@copilot 1. Use XML when it can improve efficiency. 2. Use CoT structure. 3. 在开始编写任何代码之前，请先根据本 Spec 描述你对任务的理解。如果 Spec 中存在冲突，请立即指出。 ** Update in this PR **

[Copilot]

@copilot 1. Use XML when it can improve efficiency. 2. Use CoT structure. 3. 在开始编写任何代码之前，请先根据本 Spec 描述你对任务的理解。如果 Spec 中存...

Done in b97e569. Here's what was applied:

1. CoT structure — the document now opens with a <cot> block containing:

• <understanding> — project summary derived from the spec
• <conflicts> — 3 conflicts identified and resolved:
  • C1: Dual Transfer Engine (stable TE vs. TENT behind USE_TENT=OFF)
  • C2: PyPI package named mooncake-transfer-engine but covers the full platform
  • C3: Two store access paths (coro_rpc HA vs. REST proxy without HA guarantees)
• <analysis> — numbered reasoning steps from dependency discovery → API extraction

2. XML where it improves efficiency — structured sections now use XML (self-describing, machine-parseable):

• <dependencies> with version, source, and role attributes
• <architecture> with nested <layer> / <component> elements
• <transports> registry with protocols and hardware attributes
• <dataflow> with <step> elements (actor, call, input, output)
• <api> metadata wrappers around C++ / Python code blocks
• <style>, <constraints>, <build-options>, <ci> for structured config

Fenced code blocks are kept for actual C++/Python syntax where XML would add no value. Simple 2-column lookups remain as Markdown tables.

[stmatengss]

@copilot Is it suitable for the current position described in PROJET_SEPC.md?

[Copilot]

@copilot Is it suitable for the current position described in PROJET_SEPC.md?

The root level is not the right position. Root is reserved for standard GitHub community health files (README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.md). All technical documentation in this repo lives under docs/source/, with design documents specifically in docs/source/design/.

Fixed in 1a9d0d8:

• Moved PROJECT_SPEC.md → docs/source/design/project-spec.md
• Added design/project-spec to the Sphinx toctree in docs/source/index.md so it appears under the Design Documents section alongside architecture, mooncake-store, transfer-engine, etc.

[github-actions]

This PR has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. Please update the PR or comment to keep it open.

[github-actions]

This PR was closed because it has been inactive for 104 days. Feel free to reopen if you'd like to continue the work.