架构

本指南说明 luna_thread 的 MoonBit 包、C 运行时和 JavaScript 插件如何组合在一起，以及哪些整数编码会跨越外部函数接口。各个包页面详细描述了每个 MoonBit 包。

层次

规范列出了两条实现路径：

MoonBit facade -> MoonBit C FFI  -> C wrapper  -> C runtime
MoonBit facade -> MoonBit JS FFI -> JS wrapper -> N-API addon -> C runtime

第一条路径已经存在。第二条路径止步于 MoonBit 一侧：backend/js 只给出 JavaScript 目标，js/ 中的插件只导出一个 runtimeName 函数。

MoonBit 包之间的依赖没有环：

包	导入
`shared`	只有核心库
`plan`	`shared`
`workflow`	`plan`, `shared`
`backend/js`	`plan`, `shared`
`backend/native`	`plan`, `shared`, `workflow`
`core`	`backend/native`, `plan`, `shared`, `workflow`

shared 包含其他所有包都使用的词汇：后端目标、执行模式、顺序保证、执行策略及其验证、运行时能力表，以及 C 请求结构体的整数编码镜像。
plan 描述作用于带类型输入域的单个数据并行操作，并按 v1 子集检查它。
workflow 描述一个任务图，其节点可以是计算计划，也可以是绑定到能力的同步步骤，并检查其结构。
backend/native 把计划转换为带类型的原生请求，调用 C 内核，并把工作流编组后交给 C 调度器。
根包 core 以默认值重新导出常用入口，并把提交路由到原生后端。

C 运行时

运行时由一个 C 文件和一个头文件组成：

文件	作用
`native/include/luna_thread_runtime.h`	公开的 C API：状态码、请求结构体、工作流类型。
`native/src/runtime.c`	内核、验证和工作流调度器。
`luna_thread/backend/native/ffi_runtime_impl.c`	同一份源码，作为 MoonBit 原生桩编译；它只有 `#include` 路径不同。
`luna_thread/backend/native/ffi_runtime_bridge.c`	把 MoonBit 参数转换为请求结构体的 `luna_mbt_*` 包装函数。
`luna_thread/backend/native/ffi_stub.c`	`luna_mbt_*` 包装函数的声明。
`native/tests/smoke.c`	内核及其失败状态的 C 冒烟测试。

运行时的两份副本必须手工保持一致。

有两种构建方式。moon 用系统 C 编译器编译桩，且不带 OpenMP 选项，因此 #pragma omp 循环在调用线程上运行，而工作流调度器仍会启动 POSIX 线程。CMake（make native-configure、make native-build）在开启 LUNA_THREAD_ENABLE_OPENMP 时把 native/ 构建为启用 OpenMP 的静态库，并一同构建冒烟测试。原生后端设计解释了这两种执行模型。

跨越接口的编码

所有枚举都以 Int 的形式跨越 C 接口。MoonBit 一侧在 backend/native 中映射它们（状态码则在 shared 中）。

状态码

编码	C 名称	MoonBit `NativeStatus`
0	`LUNA_THREAD_STATUS_OK`	`Ok`
1	`INVALID_ARGUMENT`	`InvalidArgument`
2	`UNSUPPORTED_BACKEND`	`UnsupportedBackend`
3	`UNSUPPORTED_MODE`	`UnsupportedMode`
4	`UNSUPPORTED_VALUE_TYPE`	`UnsupportedValueType`
5	`UNSUPPORTED_REDUCTION_KERNEL`	`UnsupportedReductionKernel`
6	`OVERFLOW`	`Overflow`
7	`NULL_POINTER`	`NullPointer`
8	`UNSUPPORTED_RUNTIME_PRIMITIVE`	无
9	`RUNTIME_BROKEN`	无
10	`CHANNEL_EMPTY`	无
11	`CHANNEL_CLOSED`	无
12	`MUTEX_PROTOCOL_ERROR`	无
13	`CONDVAR_PROTOCOL_ERROR`	无
14	`BARRIER_BROKEN`	无

编码 8 到 14 只来自工作流运行时；WorkflowResult::status 以原始整数携带它们。

工作流编码

编码	节点种类	能力种类	边种类	运行时状态
0	`Compute`	`OwnedBuffer`	`DataDependency`	`Submitted`
1	`Spawn`	`SharedReadView`	`ControlDependency`	`Running`
2	`Join`	`AtomicCell`	`OwnershipTransfer`	`Completed`
3	`Send`	`Mutex`	`SynchronizationDependency`	`Failed`
4	`Recv`	`Condvar`		`Rejected`
5	`Lock`	`RwLock`
6	`Unlock`	`Semaphore`
7	`Wait`	`Barrier`
8	`Signal`	`Channel`
9	`Barrier`	`Opaque`
10	`ReadShared`
11	`WriteShared`

值类型 I32 为 0，I64 为 1；归约内核 Sum 为 0，Min 为 1，Max 为 2。

JavaScript 插件

js/ 是一个 node-gyp 项目（make js-install、make js-build），其 C 源码只注册一个函数 runtimeName，返回 "luna_thread_addon"。它还没有链接 C 运行时。

规范

doc/attachments/moonbit_parallel_spec/main.typ 是具有规范效力的英文规范，main.zh_CN.typ 是其中文镜像；make docs 会编译两者。规范定义了工作流演算、所有权转移、ABI 布局以及一致性义务。实现覆盖了第一部分的数据模型和验证，以及其中一个子集的原生实现；各包的设计页面说明具体覆盖了哪些部分。docs/spec-review-report-zh.md 用中文记录了评审意见。

仓库布局

路径	内容
`luna_thread/`	MoonBit 模块（`moon.mod`）及其包。
`native/`	C 运行时、头文件、CMake 构建和冒烟测试。
`js/`	Node.js 插件的脚手架。
`doc/`	本手册、其翻译和规范。
`scripts/check-env.sh`	检查 MoonBit、C、Node.js 和 Typst 工具链。
`Makefile`	用于检查、构建原生运行时和插件以及编译规范的快捷命令。