compiler 模块注释完善：Doxygen 风格（Lexer/Parser/Linker/Typecheck/Project/MachineConfig/TypeInfo/Codec/Codegen/Stb/main 共 21 个文件）

compiler/src/Stb.cpp

@@ -3,6 +3,10 @@
  * @brief 编译器自带的 .stb 映像规范（写侧）+ 只读视图 + FNV-1a + sidecar
  * @author 
  * @date 2026-08-21
+ *
+ * @details 与 vm 侧各一份实现；格式契约见 Doc/isa/指令与映像.md。
+ * 12.13 修订已落地：头 104 = 原 72 + 型号标识[32] @72，文件尾 SHA-256[32]；
+ * 工程哈希为 FNV-1a 64。
  */
 
 #include "compiler/Stb.h"
@@ -15,6 +19,14 @@
 
 namespace compiler {
 
+/**
+ * @brief FNV-1a 64 增量哈希更新（工程哈希，非密码学）。
+ * @param h 当前哈希（首轮传 kFnvBasis）
+ * @param data 输入字节
+ * @param len 字节数
+ * @return 更新后的哈希值
+ * @details 每字节：h ^= byte; h *= kFnvPrime。
+ */
 uint64_t fnv1a64_update(uint64_t h, const uint8_t* data, size_t len) {
     for (size_t i = 0; i < len; ++i) {
         h ^= data[i];
@@ -23,12 +35,19 @@ uint64_t fnv1a64_update(uint64_t h, const uint8_t* data, size_t len) {
     return h;
 }
 
+/**
+ * @brief FNV-1a 64 一次性哈希（工程哈希）。
+ * @param data 输入字节
+ * @param len 字节数
+ * @return 哈希值（从 kFnvBasis 起）
+ */
 uint64_t fnv1a64(const uint8_t* data, size_t len) {
     return fnv1a64_update(kFnvBasis, data, len);
 }
 
 namespace {
 
+    /// 小端读 32 位。
     uint32_t get_le32(const uint8_t* p) {
         return static_cast<uint32_t>(p[0])
             | (static_cast<uint32_t>(p[1]) << 8)
@@ -36,6 +55,7 @@ namespace {
             | (static_cast<uint32_t>(p[3]) << 24);
     }
 
+    /// 小端读 64 位。
     uint64_t get_le64(const uint8_t* p) {
         uint64_t v = 0;
         for (int i = 0; i < 8; ++i) {
@@ -46,6 +66,7 @@ namespace {
 
     // ---- SHA-256（FIPS 180-4）----
 
+    /// SHA-256 轮常量 K[0..63]。
     const uint32_t kShaK[64] = {
         0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
         0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
@@ -60,15 +81,26 @@ namespace {
         0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
     };
 
+    /// 循环右移。
     inline uint32_t rotr(uint32_t x, uint32_t n) { return (x >> n) | (x << (32 - n)); }
 
+    /**
+     * @brief SHA-256 增量状态机。
+     * @details 标准 FIPS 180-4 实现：update() 吸收任意长度字节流，final() 输出
+     *          32 字节大端摘要。按 64 字节块 process()。
+     */
     struct Sha256 {
         uint32_t h[8] = {0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
-                         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};
-        uint64_t total = 0;
-        uint8_t block[64];
-        size_t block_len = 0;
+                         0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19};  ///< 初始哈希值
+        uint64_t total = 0;   ///< 已吸收字节数（final 时编码进长度域）
+        uint8_t block[64];    ///< 当前块缓冲
+        size_t block_len = 0; ///< 块缓冲已用字节数
 
+        /**
+         * @brief 吸收数据。
+         * @param data 输入字节
+         * @param len 字节数
+         */
         void update(const uint8_t* data, size_t len) {
             total += len;
             while (len > 0) {
@@ -91,6 +123,7 @@ namespace {
             }
         }
 
+        /// 压缩一个满块（64 字节：w[0..63] 展开 + 64 轮）。
         void process() {
             uint32_t w[64];
             for (int i = 0; i < 16; ++i) {
@@ -123,6 +156,10 @@ namespace {
             h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
         }
 
+        /**
+         * @brief 结束并输出摘要。
+         * @param out 32 字节输出缓冲（大端）
+         */
         void final(uint8_t out[32]) {
             const uint64_t bitlen = total * 8;
             const uint8_t pad = 0x80;
@@ -146,6 +183,7 @@ namespace {
             }
         }
 
+        /// 大端读 32 位。
         static uint32_t get_be32(const uint8_t* p) {
             return (static_cast<uint32_t>(p[0]) << 24) | (static_cast<uint32_t>(p[1]) << 16) |
                    (static_cast<uint32_t>(p[2]) << 8) | static_cast<uint32_t>(p[3]);
@@ -154,12 +192,25 @@ namespace {
 
 }  // namespace
 
+/**
+ * @brief 一次性 SHA-256（文件完整性校验）。
+ * @param data 输入字节
+ * @param len 字节数
+ * @param out 32 字节摘要输出（大端）
+ */
 void sha256(const uint8_t* data, size_t len, uint8_t out[kSha256Size]) {
     Sha256 s;
     s.update(data, len);
     s.final(out);
 }
 
+/**
+ * @brief 按型号标识约定填充 32 字节：name + version（如 "STATOR1"）。
+ * @param name 型号名
+ * @param version 版本号
+ * @param out 32 字节输出缓冲
+ * @details 不足补 '\0'，超长截断。
+ */
 void fill_model_id(const std::string& name, uint32_t version, char out[kModelIdSize]) {
     const std::string id = name + std::to_string(version);
     for (size_t i = 0; i < kModelIdSize; ++i) {
@@ -167,6 +218,19 @@ void fill_model_id(const std::string& name, uint32_t version, char out[kModelIdS
     }
 }
 
+/**
+ * @brief 从原始字节构造只读视图（不拷贝，调用方保证生命周期）。
+ * @param buf 映像缓冲；可为 nullptr
+ * @param len 缓冲字节数
+ * @return 校验结果；ok() 判成功，error() 取失败原因
+ * @details 校验顺序：长度 ≥ 头 → 魔数 → 版本 → 段偏移范围/单调 →
+ * 常量表/函数表大小 → 代码段 4 字节对齐 → 入口 fn_id 范围；
+ * 错误消息："null buffer" / "image too short" / "bad magic" /
+ * "bad version" / "missing sha256 tail" / "segment offset out of range" /
+ * "segment offsets not monotonic" / "const table size mismatch" /
+ * "function table size mismatch" / "code segment not 4-byte aligned" /
+ * "entry fn_id out of range"。
+ */
 StbView StbView::from(const uint8_t* buf, size_t len) {
     StbView v;
     v.buf_ = buf;
@@ -236,10 +300,12 @@ StbView StbView::from(const uint8_t* buf, size_t len) {
     return v;
 }
 
+/// 从 vector 构造（转发 from(buf.data(), buf.size())）。
 StbView StbView::from(const std::vector<uint8_t>& buf) {
     return from(buf.data(), buf.size());
 }
 
+/// 读常量表一行；越界或未 ok() 时返回全 0。
 ConstEntry StbView::const_entry(size_t i) const {
     ConstEntry e;
     if (ok_ && i < n_consts_) {
@@ -250,11 +316,13 @@ ConstEntry StbView::const_entry(size_t i) const {
     return e;
 }
 
+/// 常量表段起点（头 @52；由 from() 已校验的段起点）。
 uint32_t StbView::offs_of_const() const {
     // offset_const = offs[0]，由 from() 已校验的段起点
     return static_cast<uint32_t>(get_le32(buf_ + 52));
 }
 
+/// 读函数表一行；越界或未 ok() 时返回全 0。
 StbView::FuncRow StbView::func_row(size_t i) const {
     FuncRow r;
     if (ok_ && i < n_funcs_) {
@@ -266,22 +334,27 @@ StbView::FuncRow StbView::func_row(size_t i) const {
     return r;
 }
 
+/// 字节码段起点（未 ok() 时返回 nullptr）。
 const uint8_t* StbView::code_bytes() const {
     return ok_ ? buf_ + offset_code_ : nullptr;
 }
 
+/// 字节码段字节数（未 ok() 时返回 0）。
 size_t StbView::code_len() const {
     return ok_ ? offset_fb_ - offset_code_ : 0;
 }
 
+/// 数据段起点（未 ok() 时返回 nullptr）。
 const uint8_t* StbView::data_bytes() const {
     return ok_ ? buf_ + offset_data_ : nullptr;
 }
 
+/// 数据段字节数（不含文件尾 SHA-256；未 ok() 时返回 0）。
 size_t StbView::data_len() const {
     return ok_ ? (len_ - kSha256Size) - offset_data_ : 0;
 }
 
+/// 型号标识字符串（头 72..103，截断到首个 '\0'；未 ok() 时返回空串）。
 std::string StbView::model_id() const {
     if (!ok_) {
         return "";
@@ -294,12 +367,14 @@ std::string StbView::model_id() const {
     return s;
 }
 
+/// 型号标识是否匹配 name + version（未 ok() 时返回 false）。
 bool StbView::model_matches(const std::string& name, uint32_t version) const {
     char want[kModelIdSize];
     fill_model_id(name, version, want);
     return std::memcmp(buf_ + 72, want, kModelIdSize) == 0;
 }
 
+/// 文件尾 32 字节 SHA-256 校验（对文件尾之前全部内容重算；未 ok() 时返回 false）。
 bool StbView::sha_ok() const {
     if (!ok_) {
         return false;
@@ -310,6 +385,13 @@ bool StbView::sha_ok() const {
     return std::memcmp(buf_ + content_len, digest, kSha256Size) == 0;
 }
 
+/**
+ * @brief 读整个文件为字节（纯字节；校验交给 StbView）。
+ * @param path 文件路径
+ * @param out 输出字节
+ * @param err 错误输出；可为 nullptr（静默）
+ * @return true 成功；false（err "cannot open for read: <path>"）
+ */
 bool read_stb_file(const char* path, std::vector<uint8_t>* out, std::string* err) {
     std::ifstream in(path, std::ios::binary);
     if (!in) {
@@ -322,6 +404,13 @@ bool read_stb_file(const char* path, std::vector<uint8_t>* out, std::string* err
     return true;
 }
 
+/**
+ * @brief 写字节为文件（纯字节）。
+ * @param path 文件路径
+ * @param img 映像字节
+ * @param err 错误输出；可为 nullptr（静默）
+ * @return true 成功；false（err "cannot open for write: <path>" / "write failed: <path>"）
+ */
 bool write_stb_file(const char* path, const std::vector<uint8_t>& img, std::string* err) {
     std::FILE* f = std::fopen(path, "wb");
     if (f == nullptr) {
@@ -338,6 +427,13 @@ bool write_stb_file(const char* path, const std::vector<uint8_t>& img, std::stri
     return ok;
 }
 
+/**
+ * @brief 生成 sidecar 文本（TOML）。
+ * @param bindings I/O 绑定列表
+ * @return TOML 文本（每个绑定一节 [[io.input]] / [[io.output]]，含
+ *         var / slot / channel / bit 四字段）
+ * @details I/O 绑定 var → 槽号 → channel/bit（执行器采样用）。
+ */
 std::string make_sidecar(const std::vector<IoBinding>& bindings) {
     std::string out;
     for (const IoBinding& b : bindings) {
@@ -357,6 +453,13 @@ std::string make_sidecar(const std::vector<IoBinding>& bindings) {
     return out;
 }
 
+/**
+ * @brief 生成并写 sidecar 文件。
+ * @param path 文件路径
+ * @param bindings I/O 绑定列表
+ * @param err 错误输出；可为 nullptr（静默）
+ * @return true 成功；false（err "cannot open for write: <path>" / "write failed: <path>"）
+ */
 bool write_sidecar_file(const char* path, const std::vector<IoBinding>& bindings,
                         std::string* err) {
     std::FILE* f = std::fopen(path, "wb");