架构

本指南说明 linear-algebra 的各个包如何相互依赖、哪一层负责哪类决策，以及测试和文档如何组织。各包自身的设计页面解释其内部实现。

依赖图

下表列出每个包导入的内容（省略仅用于测试的导入）。不带前缀的 luna-generic 和 arithmetic 指上游模块 Luna-Flow/luna-generic 与 Luna-Flow/arithmetic。

包	导入
`algebra`	无
`arithmetic`	上游 `arithmetic`、`luna-generic`
`error`	上游 `arithmetic`
`internal`	`error`
`immut`	`error`、`internal`、`luna-generic`、core `immut/vector`
`mutable`	`error`、`internal`、`luna-generic`、上游 `arithmetic`
`backends/default`	`algebra`, `immut`, `mutable`, `luna-generic`
`container`	`error`
`container/adapters`	`container`, `error`, `immut`, `mutable`, `backends/default`
`consistency`	`immut`、`mutable`（仅测试）
`perf_support`	`mutable`, `luna-generic`, `moonbitlang/x/fs`
`perf`	`perf_support`
`perf_runner`	`perf_support`, `moonbitlang/x/fs`

由此得出三条规则：

具体包不依赖实验层。 immut 和 mutable 只导入 error、internal 以及上游标量包。它们不知道 algebra 或 container 的存在，因此这些层的变化不会破坏具体 API。
桥接包是叶子。 backends/default 将 algebra 与具体类型连接起来，container/adapters 将 container 与具体类型连接起来。没有其他包导入这些桥接包。
能力定义在实现之下。 algebra 和 container 定义 trait 与记录，而不导入任何具体类型，因此外部库可以在不依赖 immut 或 mutable 的情况下实现它们。

层次

层	包	负责
标量运算	`arithmetic`	标量运算的名称；不含定律
错误	`error`	受检 API 的失败词汇
具体存储	`immut`, `mutable`, `internal`	表示、算法、边界行为
结构	`algebra`	类型支持哪些整体运算，及其定律
桥接	`backends/default`, `container/adapters`	证明具体类型满足这些能力
互操作	`container`	元素级读取、构造与编辑，泛型转换
工具	`consistency`, `perf`, `perf_runner`, `perf_support`	测试与基准测试

选择后端就是选择类型：想用稠密可变后端的程序使用 @default.DenseMatrix 或 @mutable.Matrix；矩阵类型内部没有运行时选择器。

目标平台

mutable 为矩阵、LU、视图和转置代码在每个目标上各保留一个源文件（*_native.mbt、*_js.mbt、*_wasm.mbt、*_wasm_gc.mbt），由其 moon.pkg 中的 options(targets: ...) 选择。这些文件以不同的循环结构实现同一规范；测试关卡会在全部四个目标上运行 mutable、container、backends/default 以及文档包。

文档与测试

本手册的每个页面都以 .mbt.md 文件的形式链接到 src/doc_en_us 中。以 moonbit check 围起的代码块会作为该包的测试编译并运行；以 moonbit nocheck 围起的代码块仅作示意。
译文是 doc/locale 中的 gettext 目录，用 lunadoc 从英文页面生成。
run_test.sh 运行默认关卡：immut、consistency，并在每个目标上运行 container、container/adapters、backends/default、mutable 和 doc_en_us。设置 LINEAR_ALGEBRA_TEST_BENCH=1 会加入基准测试包。
CORRECTNESS_CHECKLIST.md 记录数值例程的审计状态。

模块之外

contrib/openblas_backend 保留了已撤下的原生 OpenBLAS 后端，附带其自身的文档和重新启用步骤。它不是本模块的包，不参与构建，也不属于本手册。

下游库构建在这些层之上；例如 geometry3d 使用了 linear-algebra。