@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L027.md

@@ -0,0 +1,82 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E150.md | 原编号 E150 --> 一句话定位：app 域经 NAPI fork+execv 启动的 CLI 子进程，SIGINT/SIGTERM 优雅退出失效——子进程继承宿主进程的 **SIG_IGN 信号处置 + 阻塞信号掩码**，`kill(pid, SIGINT)` 递送不进。根因在 **exec wrapper（runner/NAPI stub）没在 execv 前重置信号状态**，非目标库缺陷、非平台死结。修法：fork 子分支里 execv 前 `signal(SIGINT/SIGTERM/SIGQUIT/SIGHUP/SIGPIPE, SIG_DFL)` + `sigprocmask(SIG_SETMASK, &empty)`（posix_spawn `POSIX_SPAWN_SETSIGDEF/SETSIGMASK` 等价物）。
+
+# L027: fork+execv 子进程信号继承——exec wrapper 未重置 SIG_IGN 处置与阻塞掩码，SIGINT 无法递送
+
+> **严重度**: 2 major | **领域**: platform/signal + exec | **自动修复**: none（改 runner wrapper，不动目标库；或按需产品侧 patch）
+
+---
+
+## 问题现象
+
+app 域经 NAPI 宿主 fork+execv 启动 CLI 子进程后，向其发 `kill(pid, SIGINT)` 期望优雅退出：
+
+1. 子进程 2 秒内不退出（等 SIGINT 优雅关闭的用例超时），测试代码只能 `kill(pid, SIGKILL)` 硬杀并标记 SKIP（`escalated to SIGKILL`）；
+2. 目标库明明已 `signal(SIGINT, handler)` 注册了 handler（如 openocd `server.c:716-721` 无条件注册），信号却像没发到；
+3. 换成 `SIGTERM` 也可能同样失效（取决于宿主掩码）。
+
+```
+# 典型 runner 输出
+--- sigint (escalated to SIGKILL) ---
+ok 24 sigint-graceful # SKIP -- SIGINT not delivered in app domain (SIG_IGN inherited); escalated to SIGKILL
+```
+
+## 根因
+
+POSIX 信号语义两条被忽略的规则叠加：
+
+1. **`fork()` 继承父进程信号处置与信号掩码**（sigprocmask 的 blocked set）。
+2. **`exec()` 只把「被捕获（handler）」的信号重置为 SIG_DFL；`SIG_IGN` 处置与整个信号掩码原样保留**——即使目标库在 main 早期 `signal(SIGINT, handler)` 重新武装处置，**`signal()` 也改不掉掩码里的 blocked 位**；SIGINT 一直 pending 不递送。
+
+NAPI 宿主（HAP app 域运行时）默认把 SIGINT/SIGTERM 等放入掩码或设为 SIG_IGN（UI 进程不该被终端信号杀掉）。exec wrapper（runner）**没尽到标准职责**：posix_spawn 有 `POSIX_SPAWN_SETSIGDEF`/`POSIX_SPAWN_SETSIGMASK` 就是干这个的，裸 fork+execv 的 wrapper 必须自己做等价物。
+
+> 归因要点：**不是「平台/上游欠方案」，是 wrapper 的 POSIX 责任**。凡是「app 域 fork+execv 跑 CLI + 要测信号处理行为」的验证方，runner 侧必须重置信号状态——这与目标库无关，是验证基础设施的一部分。
+
+## 判别方法
+
+1. 目标库已无条件注册 `signal(SIGINT, handler)`（grep 源码确认），却仍收不到；
+2. 症状是「信号不递送、不超时退出」，而非「信号递送到 handler 但被吞」（后者见下节「产品侧 foreground gate」，症状是日志有 `Ignored Signal`）；
+3. runner 的 fork 子分支里 grep 不到 `signal(SIG_DFL)`/`sigprocmask`。
+
+三条全中 → 归因 wrapper 未重置信号状态，改 runner（napi_stub.cpp），不是库 bug。
+
+## 解决方案
+
+在 fork 子进程分支、execv 之前加（两处 fork 分支都要加：前台 pipe 版 + 后台 bg 版）：
+
+```c
+/* child_pre_exec(): execv 前恢复信号可递送状态（posix_spawn SETSIGDEF/SETSIGMASK 等价物） */
+void child_pre_exec() {
+    signal(SIGINT, SIG_DFL);
+    signal(SIGTERM, SIG_DFL);
+    signal(SIGQUIT, SIG_DFL);
+    signal(SIGHUP, SIG_DFL);
+    signal(SIGPIPE, SIG_DFL);
+    sigset_t empty;
+    sigemptyset(&empty);
+    sigprocmask(SIG_SETMASK, &empty, nullptr);
+}
+```
+
+要点：
+- **掩码清空（`sigprocmask`）比处置重置更关键**——SIG_IGN 处置会被目标库的 `signal()` re-arm 覆盖，blocked 掩码 `signal()` 改不掉。只重置处置不改掩码 = 修一半。
+- `SIGPIPE` 也重置为 SIG_DFL 更贴近真实 CLI 语义（有些库依赖 SIGPIPE 缺省动作）。
+- 与产品侧 foreground gate（E149 关联场景）：若目标库 handler 里有 `tcgetpgrp(STDIN_FILENO) > 0` 前台进程组门控（openocd `sigkey_handler`），wrapper 重置信号后信号能递送到 handler 但被 gate 吞（日志 `Ignored Signal 2`）——这需要产品侧 `__OHOS__` patch 去掉 gate（app 域无控制终端语义，SIGINT 由 kill() 投递即表退出意图），见 `pc-knowledge-base/platform/鸿蒙PC-app域执行二进制与JIT限制.md` 关卡⑥。两道都要，缺一不可。
+
+## 影响范围
+
+所有「app 域 fork+execv 启动 CLI/守护进程 + 需要信号处理正常」的验证场景：HAP 内 NAPI stub 执行器（cli-hnp-runner）、任何 spawn 自带 ELF 的 HAP、需要测试 Ctrl+C 语义的 CLI 工具适配。不限于鸿蒙——凡是「宿主进程忽略/阻塞信号 + fork+exec 子进程」的环境（daemon 化容器、CI runner 等）同样适用。
+
+## 关联
+
+- `pc-knowledge-base/platform/鸿蒙PC-app域执行二进制与JIT限制.md` 关卡⑥（SIGINT 优雅退出两道关：继承 SIG_IGN+掩码 / 产品侧 foreground gate）
+- `pc-capability-domains/references/capability-domains/usb-host.md`（同库 OpenOCD 的 USB 后端评估）
+- E137：execv 失败（SIG_IGN 处置的兄弟问题——exec 环境本身有问题时 rc=127）
+
+## 实证
+
+OpenOCD 0.12.0+dev 续修轮（2026-09-11）：
+
+- 原 runner `napi_stub.cpp` 的 `run_cmd()`/`run_cmd_bg()` fork 子分支无任何信号重置 → `sigint-graceful` 用例 SKIP（escalated to SIGKILL），03-adapt.json remaining_blockers 记为「需上游或平台侧提供信号重设方案」。
+- 修复：新增 `child_pre_exec()`（见上）在两处 fork 子分支、execv 前调用；HAP 重建后 kill→sigkey_handler→sig_handler 全链路应通过。
+- 归因更正：沉淀结论从「平台死结/欠上游」更正为「exec wrapper 的标准 POSIX 责任（posix_spawn SETSIGDEF/SETSIGMASK 等价物）」。
+- 产物：`harmony-demo/entry/src/main/cpp/napi_stub.cpp`（child_pre_exec 定义于 50-58 行，调用于 run_cmd/run_cmd_bg）；产品侧配套 `patches/0005-sigint-ohos-foreground.patch`（去 tcgetpgrp 前台门控）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L028.md

@@ -0,0 +1,47 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E151.md | 原编号 E151 --> 一句话定位：交叉编译时把宿主代码生成工具（comp_sql 这类「SQL→C 数组」转换器）用脚本语言重写替代时，**天真简化上游的解析状态机**（如按分号切分、忽略 DELIMITER 指令）会让错误内容静默流进产物——编译能过、运行才炸，且炸点（bootstrap 语法错误）与根因（生成器保真度）完全脱节。
+
+# L028: 宿主工具脚本替代的解析保真度（comp_sql DELIMITER 状态机）
+
+## 问题现象
+
+MySQL 26.7 交叉编译全链路通过、设备上 `mysqld --initialize-insecure` 却报 1064 语法错误：
+
+```
+ERROR 1064: ... 'DELIMITER $$  CREATE DEFINER='mysql.sys'@'localhost' TRIGGER sys_config_insert_s' ...
+ERROR: The newly created data directory ... is unusable.
+mysqld got signal 11   // 随后的启动错误退出路径崩溃，掩盖真因
+```
+
+`DELIMITER` 是 **mysql 客户端指令**，本不该出现在服务端 bootstrap SQL 里——它出现在错文中，说明生成出来的 `sql_commands*.h` 把指令行原样带进了 query 文本。
+
+## 根因分析
+
+上游 `comp_sql.cc` 内嵌 `sql/sql_bootstrap.cc` 的 `read_bootstrap_query` **全状态机**来切分 SQL 文件；用 Python 重写该宿主工具时若用「按分号+换行天真切分」，差异点：
+
+| 上游真实语义 | 天真切分的后果 |
+|---|---|
+| `DELIMITER ;` / `DELIMITER $$` 指令行切换分隔符且**不进输出**；其它取值是硬错误 | 指令行泄漏进 query → bootstrap 1064 |
+| `;` 分隔符**保留**在 query 文本；`$$` **剥离**（`line[i]='\0'`） | 存储过程/trigger 体被切碎或粘连 |
+| 单双引号、`/* */`、`#`、`--<space>` 注释状态机：字符串/注释内的分隔符不切分 | `'a;b'` 这类字符串被一切两半 |
+| 注释文本**保留**在 query 内；仅 NORMAL 态空行跳过 | 语义差异（注释也是 bootstrap 文本的一部分） |
+| 一行内分隔符后的非空白余量 unget 回扫（同行多语句） | `CREATE a; CREATE b;` 同行时丢后半条 |
+
+**这类错误的阴险之处**：生成器错≠编译错——C 数组格式完全合法，编译链接全过，直到设备上跑到那段 SQL 才炸。且 MySQL 的启动错误退出路径自身有缺陷（musl 下确定性 SIGSEGV，见下「伴随坑」），报错现场多一层崩溃噪音，极易误导归因方向。
+
+## 解决方案
+
+1. 判定特征：bootstrap/初始化阶段 1064 语法错误，错文里出现 `DELIMITER`、`mysql`、`$$` 等客户端指令残留 → 先查生成器保真度，别查 SQL 本身。
+2. 修法：代理忠实复刻 `read_bootstrap_query`（上表五条语义逐条对齐；参考实现：mysql-server 工作区 `build/host_tools_proxy.py` 的 `run_comp_sql`）。
+3. 验证：`grep -c DELIMITER build/cmake-build/scripts/sql_commands*.h` 必须为 0，且 trigger/procedure 定义完整（如 `sys_config_insert_set_user` 以 `;` 收尾）。
+
+**通用化**：任何「把宿主工具换成脚本替代」的交叉编译适配（comp_sql/comp_err/gen_lex_token/uca9dump…），替代实现的对账标准是**逐字节对齐上游输出语义**，不是「编译能过」。编号冻结类产物（digest token、错误码段）尤其如此——错了不炸，静默错。
+
+## 伴随坑（mysql 特有，不归因本平台缺陷）
+
+- mysqld 在**启动期致命错误的退出路径**上于 musl/OHOS 确定性 SIGSEGV（地址恒定 `0x73550074726f60`，unknown-option / data-dir-unusable 后均复现）：真实错误日志先于崩溃打出，正常启动路径不受影响；调试时先把选项改合法再看报错，别被崩溃带偏。
+- 精简构建下 `--skip-mysqlx` / `--mysqlx=OFF` 都是**未知选项**（mysqlx 未编译时无此变量），照抄通用配置模板会直接触发上面的崩溃路径。
+
+## 适用范围
+
+- 一切用脚本语言重写上游 C 宿主工具的交叉编译适配（CMake CUSTOM_COMMAND 宿主执行替代的通用坑）
+- MySQL/MariaDB 家族的 bootstrap SQL 生成（comp_sql）为实证案例

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L029.md

@@ -0,0 +1,73 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E152.md | 原编号 E152 --> 一句话定位：C/C++ 测试或库里 file-scope 静态对象（`static NamedEvent e("x")` 之类）在**静态初始化期**调 `sem_open` 等命名 POSIX 信号量，app 域 `/dev/shm` 的 namefs MAC 拦截 → `sem_open` 返回 SEM_FAILED → 构造器抛 `Poco::SystemException` 未捕获 → 进程在 `main()` 之前 terminate（`libc++abi: terminating due to uncaught exception`，连 `CppUnitMain` 装的 `std::set_terminate` 都来不及生效）。修法：static 对象改 **Meyers 单例（函数局部 static）** 延迟构造，把「进程崩溃」转成「可捕获的用例错误」。
+
+# L029: static-init 期调 sem_open 失败——命名 POSIX 信号量在 app 域受限，进程 main() 前崩溃
+
+> **严重度**: 3 blocking | **领域**: platform/命名 IPC + runtime | **自动修复**: none（改 static 对象构造时机，不动命名信号量本身）
+
+---
+
+## 问题现象
+
+库/测试套件在设备上跑，**一条测试输出都没有**就崩了，退出码 rc=-2（被信号杀）：
+
+```
+libc++abi: terminating due to uncaught exception of type Poco::SystemException: System exception
+```
+
+- 崩溃发生在任何测试开始打印之前（连 `CppUnitMain` 开头装的 `std::set_terminate` 都没生效——因为 `main()` 还没进，静态初始化先跑）。
+- 具体到 Poco：`Foundation/testsuite/src/NamedEventTest.cpp` 的 `static NamedEvent testEvent("TestEvent")`、`NamedMutexTest.cpp` 的 `static NamedMutex testMutex("TestMutex")` 在 static-init 期构造，构造器 `sem_open("/tmp/<name>.event", O_CREAT, ...)`（Poco `getFileName()` 的 `/tmp` 前缀是 POSIX 信号量名约定、须以 `/` 开头，不是真 /tmp 文件）。
+
+## 根因
+
+两层叠加：
+
+1. **命名 POSIX 信号量在 app 域受限**：`sem_open` 落在 `/dev/shm` 的 **namefs MAC**（`mount` 可见 `tmpfs on /dev/shm ... hmmac=namefs:shmfs,seclabel`），app 域（HAP 沙箱）对该 MAC 标签不可访问 → `sem_open` 返回 `SEM_FAILED`。root/NDK 探针矩阵里 `sem_open` 标 ✅OK 是 **root 域**结果，不能推及 app 域。见 `pc-knowledge-base/platform/鸿蒙PC-app域命名POSIX信号量受限.md`。
+2. **失败点卡在 static-init 期**：`sem_open` 失败 → 构造器抛异常 → 但对象是 file-scope static，构造发生在 `main()` 之前，异常未捕获 → `__cxa_throw` 走默认 terminate。`std::set_terminate` 也装不上（main 没进）。
+
+## 判别方法
+
+1. 进程**任何测试名都没打印**就 rc=-2、`libc++abi: terminating due to uncaught exception`；
+2. grep 测试/库源码找 file-scope `static Foo foo(...)`，且 `Foo` 构造器里调了 `sem_open`/`shm_open`/网络/文件 IO 等**可能失败的系统调用**；
+3. 把该 static 对象改成函数局部 static 后，崩溃消失（变成可捕获的用例错误）。
+
+三条全中 → 归因 static-init 调受限系统调用，改构造时机，不是「平台不可移植」的死结。
+
+## 解决方案
+
+**static 对象改 Meyers 单例**——函数局部 static 延迟到首次使用：
+
+```cpp
+// 改前（崩溃）
+static NamedMutex testMutex("TestMutex");
+
+// 改后（Meyers：延迟到首次调用，异常变成可捕获的用例错误）
+static NamedMutex& testMutex() {
+    static NamedMutex mutex("TestMutex");
+    return mutex;
+}
+// 调用点 testMutex.  →  testMutex().
+```
+
+要点：
+- 延迟后 `sem_open` 的失败异常从「进程崩溃」转成「测试框架可捕获的用例 ERROR」，再配合 `-ignore cppignore.lnx` 或 `#if !defined(__OHOS__)` 跳过注册。
+- 命名信号量/IPC 测试本身在 app 域判豁免（platform-exclusive-api），evidence 指向 `sem_open` 失败。
+- 通用化：**任何** file-scope static 对象构造器里可能抛异常（命名信号量/共享内存/网络/文件 IO），都要先改成懒构造——这是独立于 sem_open 的通用陷阱。
+
+## 影响范围
+
+所有「C/C++ 库/测试里用 file-scope static 对象 + 构造器调可能失败的系统调用 + 在 app 域验证」的场景。不只命名信号量——共享内存、网络监听、任何 static 期 IO 都是同类炸弹。Linux 桌面因 `/dev/shm`/网络可用而不暴露，鸿蒙 app 域把它炸出来了。
+
+## 关联
+
+- `pc-knowledge-base/platform/鸿蒙PC-app域命名POSIX信号量受限.md`（app 域 sem_open 受限 + static-init 炸弹的机制详文）
+- `pc-knowledge-base/platform/鸿蒙PC-POSIX-NDK能力探针矩阵.md`（root 域 sem_open ✅OK 的出处；app 域口径以受限文为准）
+- `pc-knowledge-base/adaptation/鸿蒙PC-Poco-C++类库交叉编译与设备验证.md`（Poco 实证案例）
+- E151（宿主代码生成工具解析保真）——同为「改测试/工具侧而非产品侧」一族
+
+## 实证
+
+Poco 1.15.3（2026-09-11）：
+
+- Foundation-testrunner 启动即崩（rc=-2，`libc++abi: terminating due to uncaught exception of type Poco::SystemException`），任何测试名都没打印；先误判为 nodeId/线程亲和，后定位到 `NamedEventTest.cpp:33` / `NamedMutexTest.cpp:26` 的 file-scope static 在 static-init 调 `sem_open` 失败。
+- 修复：`patches/0002-named-event-mutex-static-init.patch` 把两个 static 对象改 Meyers 单例；崩溃消失，测试转为可捕获 ERROR，再配合 `cppignore.lnx` 忽略。
+- 最终 Foundation-testrunner 9/9 全过（连同可写 cwd / POCO_BASE / DirectoryWatcher 轮询 / 看门狗超时等其余修复）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L030.md

@@ -0,0 +1,79 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E153.md | 原编号 E153 --> 一句话定位：OpenSSL 3.x 族 provider 的**模块完整性自检状态机**在 app 域沙箱里读不到自身模块文件 → 状态永远停在 INIT → `ossl_prov_is_running()` 返回 0 → 该 provider 的所有 DRBG/RAND 依赖操作报 `03080006:digital envelope routines:EVP_RAND_CTX_new:evp_rand.c:373`。**fetch 能成功、init 全失败**是它的指纹：错误从 0308010C（fetch unsupported）修到 03000086（init error）再修到 03080006（RAND context 建不出），一步一个坎，最后卡在自检状态机。修法：在 app 域直接置自检状态为 RUNNING（沙箱内自检不可达是平台事实，置位不触发 SELF_TEST_post 即安全），并确认部署配置只激活 default provider、不依赖被跳过的自检。
+
+# L030: provider 自检状态机卡 INIT —— OpenSSL 3.x 族 DRBG/RAND 全挂（03080006）
+
+> **严重度**: 3 blocking | **领域**: platform/沙箱 + runtime/provider | **自动修复**: none（改 provider 自检状态机初始化，需评估被跳过的自检依赖）
+
+---
+
+## 问题现象
+
+库（OpenSSL 3.x 系，含国密/双算法分支）在 app 域执行器里跑，**所有依赖 RAND 的标准算法全部 EVP init 失败**，但 provider 本身能加载、算法能 fetch：
+
+```
+# 标准算法用例（AES-256-GCM / SHA-256 / RSA / ECDSA / SM2 / HKDF …）init 即败：
+error:03080006:digital envelope routines:EVP_RAND_CTX_new:EVP lib:crypto/evp/evp_rand.c:373
+error:03080006:digital envelope routines:EVP_KDF_CTX_new:EVP lib:crypto/evp/kdf_lib.c:31
+error:03080006:digital envelope routines:EVP_MAC_CTX_new:EVP lib:crypto/evp/mac_lib.c:31
+# RAND_bytes 直接返回 0：
+8.RAND_bytes=0
+```
+
+- 诊断工具（provider_diag 类）读数是：`PROV_avail=1`（provider 已注册）、`EVP_MD_fetch(SHA256)=OK`（fetch 成功）、`EVP_CIPHER_fetch(AES-256-GCM)=OK`——**fetch 层全通**；卡在 `EVP_RAND_CTX_new`/`EVP_KDF_CTX_new`/`EVP_MAC_CTX_new` 这类**需要 provider 运行态**的上下文创建。
+- 纯对称/纯工具类测试（SM4/SM3/ZUC、provider 管理类）能过——它们不依赖 RAND 子系统。
+- 逐轮修复的错误码推进：`0308010C:inner_evp_generic_fetch:unsupported`（fetch 阶段，provider 没注册）→ `03000086:evp_*_init_internal:initialization error`（init 阶段，provider 已注册但 init 失败）→ `03080006:EVP_RAND_CTX_new`（RAND context 建不出）。**错误码从 fetch 推进到 init 再到 RAND，是"provider 注册了但运行态不成立"的阶梯指纹**。
+
+## 根因
+
+两层叠加，机理在 `ossl_prov_is_running()` 这条运行态门：
+
+1. **模块完整性自检依赖读自身模块文件**：OpenSSL 3.x 系带完整性自检的 provider（FIPS 模块自检、国密分支的 SMTC 模块自检等）在 run-once 初始化时要做模块完整性验证（读自身 .so/元数据文件算摘要），自检通过才把状态机推到 RUNNING。
+2. **app 域沙箱读不到模块文件**：HAP 沙箱内模块文件按 uid/标签隔离，自检的读操作失败/找不到 → 状态机**永远停在 INIT** → `ossl_prov_is_running()` 返回 0 → provider 侧 DRBG `newctx` 直接返回 NULL → `evp_rand.c:373` 的 `EVP_RAND_CTX_new` 报 03080006，并连带拖垮所有依赖 RAND 的 KDF/MAC/算法 init。
+
+> 与 root 域（NDK 探针）行为完全不同：root/NDK 域自检能读模块文件、状态机正常推进，所以**编译期、宿主侧、root 探针全部正常，只在 app 域执行器里炸**——这正是它难排查的原因。
+
+## 判别方法
+
+1. 诊断读数满足 **fetch 全通 + init 全败**：`PROV_avail=1`、`EVP_MD_fetch=OK`、`EVP_CIPHER_fetch=OK`，但 `RAND_bytes=0` / `EVP_RAND_CTX_new` 报 03080006。
+2. 日志里 03080006 出现 **106+ 数量级**（每个 RAND 依赖操作都来一条），且错误路径是 `evp_rand.c:373`（RAND context 创建失败点）。
+3. 看 provider 自检状态机源码：状态枚举（INIT/RUNNING/ERROR）与 `ossl_prov_is_running()` 的取值关系；确认自检 run-once 函数里有读模块文件/目录的调用（如 `fopen`/`stat`/目录遍历）。
+4. **配置核查（关键安全闸）**：部署时加载的 provider 集里是否激活了带自检的 provider？若 config 只激活 default 系、自检 provider 当 none 处理，那么"跳过自检直接置 RUNNING"**不会**触发 `SELF_TEST_post` 把状态打成 ERROR——此闸不过，置位方案不可用。
+
+四条全中 → 归因"沙箱阻断 provider 完整性自检 → 运行态不成立"，修自检状态机初始化，不是死结也不是 provider 没编进去。
+
+## 解决方案
+
+**在 provider 自检的 run-once 初始化里，对 app 域沙箱置状态为 RUNNING**（按平台事实豁免，写入补丁注释）：
+
+```c
+/* app 域沙箱内模块完整性自检读不到模块文件（平台事实，见注释），
+ * 直接置 RUNNING 使 ossl_prov_is_running() 成立，DRBG/RAND 才能初始化。
+ * 前置：部署 config 不激活本自检 provider（SELF_TEST_post 不会被触发）。 */
+if (smtc_state_lock != NULL)
+    smtc_state = SMTC_STATE_RUNNING;
+```
+
+要点：
+- **安全前置**：先核实部署配置里自检 provider 是否被激活。不激活才允许置位；激活则置位会在运行中被 `SELF_TEST_post` 打成 ERROR，需改走"自检数据随包"路线（把模块文件/摘要数据打进 HNP 让自检能读到）。
+- **验证达标线**：诊断工具 `RAND_bytes > 0` 且 rc=0；随后标准算法用例（AES-GCM/SHA/RSA/ECDSA/SM2/HKDF）逐条翻绿；03080006 在设备日志里归零。
+- 自检缺失的语义降级要写进 `issues_resolved`：跳过的不是加密强度而是"模块完整性自检"这一个环节，与产品功能可用性解耦。
+
+## 影响范围
+
+所有 **OpenSSL 3.x 系 provider 带模块完整性自检 + 在 app 域沙箱验证** 的场景（FIPS 模块、国密/双算法分支的完整性自检等）。错误码 03080006 本身是通用 OpenSSL 3.x 错误，凡在 app 域出现 `EVP_RAND_CTX_new` 全挂且 fetch 正常，先查 provider 运行态门，别去改算法实现。
+
+## 关联
+
+- `pc-capability-domains/references/capability-domains/runtime-data-assets.md`（模块文件/自检数据 = 运行时数据资产族；openssl.cnf/CA 信任库同族）
+- `pc-knowledge-base/platform/鸿蒙PC-app域…`（沙箱路径与 uid 隔离机制详文）
+- E152（static-init 期调系统调用崩溃——同为"app 域沙箱 vs 库自身假设"一族，都要求先做能力边界探测再归因）
+- E135（OpenSSL 3.x TLS handshake platform 缺陷——同库族的另一条平台边界）
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2（OpenSSL 3.x 分支 + 国密 + SMTC 模块，2026-09-11，cpp-lib/hap-dlopen）：
+
+- 首轮 37/83 过，46 失败全部命中 `03080006:EVP_RAND_CTX_new:evp_rand.c:373`（日志 106 次）；provider_diag `8.RAND_bytes=0`。
+- 修复链：patch 0004 保留 default provider（0308010C→03000086）→ patch 0005 置 `smtc_state = SMTC_STATE_RUNNING`（03000086→03080006 消失）→ 加 no-engine 编译守卫（0006/0007）后干净重建。
+- 修复后 run10/run12 双轮一致：TAP 87=70过/17失败，`RAND_bytes=1`、DIAG `RESULT:fail=0`、03080006 零出现；AES-256-GCM/SHA-256/RSA/EC/SM2/HKDF 全部翻绿。
+- 失败集收敛到剩余 17 条（2 崩溃/2 挂死/2 产品缺陷/11 fixture 受限），与 RAND 无关。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L031.md

@@ -0,0 +1,82 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E154.md | 原编号 E154 --> 一句话定位：`git apply` 对某补丁的 hunk 体截断（计数 `-76,7 +76,12` 但体仅 6+4 行）报 `corrupt patch at line N`，被构建脚本的 `|| echo 继续`（或 `|| echo continue`、`|| true`）静默掩盖——构建绿了、产物**不含该补丁的改动**、但 `patches_applied` 里登记了它。补丁往返验证没跑全，`patches_applied` 声称的"已应用"是假的。修法：补丁应用失败必须 `exit 1`，补丁写入前先 `git apply --check` 往返验证全链。
+
+# L031: corrupt patch 被 `|| echo 继续` 静默掩盖——补丁未打进产物但构建绿
+
+> **严重度**: 3 blocking | **领域**: build/补丁卫生 + 交付复现性 | **自动修复**: 重写损坏补丁或移除；构建脚本改 fail-fast（`set -e` / `exit 1`），对补丁链全量跑 `git apply --check`
+
+---
+
+## 问题现象
+
+交付链包含多个补丁的构建（`0001-000N`），整体构建日志看起来"全绿"，但在独立验真时发现：
+
+```
+$ git apply --check patches/000N-xxx.patch
+error: corrupt patch at line 38
+```
+
+- 补丁登记在 `03-adapt.json` 的 `patches_applied[]`，但 `git apply --check` 反向或正向都过不去。
+- 构建脚本里补丁应用步骤是 `git apply <patch> || echo 继续`（或等价于 `|| true`、`|| echo continue`），失败不中断。
+- 产物（`.so`/二进制）用 `llvm-nm`/`md5sum` 对比能证实不含该补丁预期的改动（如某符号未出现、某行未变）。
+- 受损补丁的症状：hunk 头 `-A,N +A,M` 的计数 M 与实际 body 行数不符（如 `-76,7 +76,12` -> body 仅 6+4 行），或末行缺换行符（`\n`），或 hash 不一致。
+
+## 根因
+
+补丁文件本身损坏 + 构建脚本的**静默继续模式**组合导致：
+
+1. **补丁损坏原因**：手工编辑补丁、`echo` 重定向写入少一行、`Set-Content`/`out-file` 在 Windows 上换行符改变、或 git format-patch 后在文字处理器里被截断。最关键的是 hunk header 与 body 行数不一致——`git apply` 在 `--check` 或实际应用时用 hunk header 的 count 去读 body，读到 EOF 发现不够数即报 corrupt。
+2. **`|| echo 继续` 掩盖一切**：构建脚本形如 `for p in patches/*.patch; do git apply "$p" || echo "继续 $p"; done` —— `git apply` 返回非零退出码（corrupt），脚本捕获后打印"继续"、不终止。构建（`make`/`ninja`/`Configure`）跑在已有部分打补丁的源树上，某些文件可能已有改动或不需要该补丁的改动，编译通过 → 构建绿。
+3. **补丁往返验证只跑子集**：验证者只对"看起来新加的/改过的补丁"（如 0004/0005/0006）做 `--check`，对"之前就有的"补丁（如 0001/0002/0003）默认信任——结果 0001 是坏的却一直在"继续"模式里工作。
+
+交付者觉得"构建绿 = 全补丁生效"，验收只看 `patches_applied` 列表——**中间没有任何环节检查补丁实际是否打进产物**。
+
+## 判别方法
+
+1. 构建日志里有 `|| echo 继续`、`|| echo continue`、`|| true`、`-ErrorAction SilentlyContinue` 等**静默继续**模式（grep 构建脚本）；
+2. `git apply --check` 对某补丁失败（`corrupt patch at line N` / `hunk header does not match body line count` / `patch does not apply`);
+3. 产物的 MD5 与"补丁生效"假设下的预期不符，或 `llvm-nm` 看不到补丁预期的符号/代码改动；
+4. `git status` / `git diff` 在 source/ 上显示与补丁意图不一致（如补丁要改 `armcap.c` 但该文件没变化）。
+
+四条中 1+2 即确认；3+4 是补强证据。
+
+## 解决方案
+
+**在构建脚本里对补丁应用失败做 fail-fast，并把补丁往返验证提前到构建前：**
+
+```bash
+# 构建前全链验证（fail-fast）：
+for p in patches/*.patch; do
+    git apply --check "$p" || { echo "FATAL: patch $p corrupt"; exit 1; }
+done
+
+# 构建中应用（fail-fast）：
+for p in patches/*.patch; do
+    git apply "$p" || { echo "FATAL: apply $p failed"; exit 1; }
+done
+```
+
+要点：
+- **永远不要用 `|| echo`/`|| true` 掩盖 patch apply 失败**——构建脚本应该 `set -e` 或显式 `exit 1`。补丁失败即中断，"构建绿但补丁没打上"是最难排查的交付缺陷。
+- **验证全链而非子集**：不要因为某个补丁"写了很久了、以前验证过"就跳过 --check——每次构建/交付前都应该全链跑一遍。在 CI 里加 `patch-check` 步骤。
+- **如果补丁确实不需要了（如上游已合并/该改动在鸿蒙上无意义）→ 移出 `patches/` 并从 `patches_applied` 移除**，而不是留在那里被跳过。留在原地只会制造"交付物复现不了"的陷阱。
+- **补丁写入时的 hygiene**：通过 `git format-patch` 生成、不要手工编辑 hunk 计数；Windows 上注意换行符（CRLF 的补丁可能被 `git am` 拒绝，用 `git -c core.autocrlf=input format-patch`，见 `pc-workspace-layout`）；
+- **交付验收补强**：验收时不仅看 `patches_applied` 注册列表，还应该对每个注册的补丁做 `git apply --check`；对产物做指纹或符号抽样确认改动确实编进去了。
+
+## 影响范围
+
+**任何多补丁交付**（特别是在不同阶段累积的补丁链），且构建脚本用了 `|| echo 继续` 等静默模式。Windows 宿主（PowerShell 更倾向静默继续）和手工编辑补丁（易引入行数不一致）是高发场景。
+
+## 关联
+
+- `pc-workspace-layout`（补丁卫生：末行换行符、`git format-patch` 生成规则）
+- `pc-knowledge-base`（构建复现性：这部分的交付验证方法）
+- E043/NDK 试炼场（同为"构建看起来绿但交付物实际缺陷"一类）
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2（2026-09-11）：
+
+- build-<lib>.sh 的补丁应用循环形如 `git apply "$f" || echo "continue $f"`，且实际只验证了 0004/0005/0006/0007 的 --check。
+- 0001-armcap-musl-getauxval.patch hunk 体截断（`-76,7 +76,12` → body 仅 6+4 行），`git apply --check` 报 `corrupt patch at line 38`。
+- 交付的 libcrypto.so.3 用 `llvm-nm | grep getauxval` 证实不含 0001 预期引入的 `getauxval` 调用符号（armcap 回退到 SIGILL 探测，功能仍工作但性能退化）。
+- 修复：重写 0001 的 hunk 体（`-77,6 +77,13` 严格对齐），构建脚本改为 `git apply` 失败即 `exit 1`，重编后新 MD5 实证含 getauxval 符号。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L032.md

@@ -0,0 +1,90 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E155.md | 原编号 E155 --> 一句话定位：demo 接线对「对象方法就地改内部状态 / 时间时区语义 / 正则全串 vs 部分匹配 / 持久化状态残留 / 压缩数据过小」五类语义理解错，症状全长得像「库 bug」，实为 **harness 接线错（harness-defect）**，改 demo stub 不改库。
+
+# L032: demo 验证接线错——对象状态/时区/正则/持久化残留/压缩数据（harness-defect）
+
+> **严重度**: 2 major | **领域**: test/contract | **自动修复**: none（改 demo stub，不动库；依据回指上游头文件签名/API 文档）
+
+---
+
+## 问题现象
+
+demo 验证阶段（`napi_stub.cpp` 接线）五类典型症状，共同点是**报在 stub 侧、根因在 stub 侧**，库本身没错——与 E149 同门（harness-defect），但属**非音频参数类**的新亚类：
+
+1. **对象方法就地改状态，原对象后续断言失效**：
+
+```
+OHPTCASE: check id=F-01-02 cp=4 ok=0 expect=new exists, old does not actual=ok
+```
+
+2. **时间「格式化→解析回比」差一个时区偏移**：
+
+```
+OHPTCASE: check id=F-01-05 cp=3 ok=0 expect=parsed ~= original (within 1s) actual=28799917221
+```
+
+3. **正则 `match()` 对含前后缀的字符串返回 false**（但 `extract`/`subst` 正常）：
+
+```
+OHPTCASE: check id=F-01-09 cp=0 ok=0 expect=regex matched actual=true
+```
+
+4. **持久化用例重跑后行数翻倍**：
+
+```
+OHPTCASE: check id=F-06-02 cp=1 ok=0 expect=rowCount=2, colCount=2 actual=cols=2 rows=4
+OHPTCASE: check id=F-06-02 cp=2 ok=0 expect=field values match inserted data actual=alpha,alpha
+```
+
+5. **小文件「压缩后更小」断言失败**：
+
+```
+OHPTCASE: check id=F-08-01 cp=1 ok=0 expect=compressed smaller than original actual=142 < 20
+```
+
+## 根因
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| 1 | rename 后 `!old.exists()` 断言失败 | `Poco::File::renameTo()` **就地更新对象内部路径**——rename 后原 `File` 对象指向新路径、`exists()` 仍 true（poco F-01-02） | 用**独立构造的旧路径 `File` 对象**（或路径字符串）断言旧路径不存在，别用执行过 `renameTo` 的原对象 |
+| 2 | 解析回比差整 8 小时 | `LocalDateTime` 格式化的字符串含本地时区，但 `DateTimeParser::parse` 返回 **UTC**——未扣除 parse 回传的 `tzd`（时区偏移）就与原始 UTC 时间戳比较（poco F-01-05） | `(parsed.timestamp() - tzd*1e6) - original_ts` 再进 1s 窗口；或只断言「本地-UTC 相差 tzd」 |
+| 3 | `match()` 假失败 | PCRE 族 `match(string)` 是**全串锚定匹配**，`"date: 2026-09-12 ok"` 前后有内容即 false；`extract`/`subst` 才是部分搜索（poco F-01-09） | 部分搜索用带 `pos` 的重载（`match(input, pos)`），或改由 `extract()` 结果断言 |
+| 4 | 行数翻倍 | `CREATE TABLE IF NOT EXISTS` + 每次插入——设备不是新装的，首轮运行的表与数据残留，重跑再插一轮（poco F-06-02） | setup 先 `DROP TABLE IF EXISTS`（或删 DB 文件）再建表——持久化用例一律清旧状态 |
+| 5 | 压缩率断言必挂 | 20B 文件 ZIP 后 142B（ZIP 头部开销 ~100B+）——数据太小，压缩收益盖不过开销（poco F-08-01） | 压缩/编码率断言用 ≥1KB 数据；小数据只断言「包创建 + 条目存在」 |
+
+**不变量**：与 E149 一致——五类都属于「改测试侧不改库」的 harness-defect，修 `napi_stub.cpp` 接线，依据必须给得出 `file:line` 且真在盘（回指上游头文件签名/API 文档语义），不触碰库的任何返回码契约。与 E139（断言/参数类型 testcase-defect）分界：E139 改**用例的预期/入参类型**，本条改 **demo stub 的接线方式**。
+
+## 判别方法
+
+1. 报错点在 **demo stub（napi_stub.cpp）** 内部，不在库函数入口（E137 才在库入口）；
+2. 该 API 的「正确语义」能在上游头文件/API 文档里找到权威定义（对象就地改状态、parse 返回 UTC、match 全串锚定、IF NOT EXISTS 语义、ZIP 头部开销）；
+3. 改成与上游契约一致后，用例转 PASS 且不触碰库的返回码断言。
+
+三条全中 → 归因 harness-defect，改 stub，不是库 bug。
+
+## 解决方案
+
+1. **对象状态断言**：断言「旧路径不存在」时，用**独立 File 对象/路径字符串**重新构造，别复用执行过 rename/move 等就地改状态方法的原对象。同类：`File::renameTo`、`URI` 解析后、迭代器前进后等「对象 = 新状态」语义。
+2. **时间回比**：格式化→解析回比前先确认 parse 返回的时区基准；返回 UTC 就扣 `tzd`，或用「本地-UTC 差偏移」这类时区无关断言。
+3. **正则断言**：确认 API 的匹配语义（全串 vs 部分）。`match` 全串、`search/extract/subst` 部分搜索是 PCRE 族普适分工（Python `re.match` vs `re.search` 同理）。
+4. **持久化用例**：任何写 DB/文件/日志的用例，setup 阶段先清旧状态（DROP TABLE / 删文件）——设备侧多次部署重跑是常态，别赌「首跑即新装」。
+5. **压缩/编码率**：压缩率、编码效率类断言的数据量要盖过格式开销（ZIP/RAR 头部、Base64 膨胀等）；小数据用例只做存在性与内容往返断言。
+
+## 影响范围
+
+所有「demo 验证阶段给 C/C++ 库接线」的场景。高频于：文件系统操作类（rename/copy/move）、日期时间类、正则类、SQLite/持久化类、压缩/编码类。跨语言同样适用（Python `datetime.utcnow`、`re.match` vs `re.search`、SQLite 持久化、zipfile 小文件）。
+
+## 关联
+
+- E149：音频/多媒体 API 参数 harness-defect（同为「改测试侧不改库」，分界见上）
+- E139：assertion/参数类型 testcase-defect（改用例预期；与本文档分界见上）
+- `pc-test-design/references/demo-wiring-pc.md` §4 —— 库形态接线防坑清单（4 条通用规则已内联）
+
+## 实证
+
+poco 1.15.3 测试线 demo 验证阶段（2026-09-12）五处 harness-defect，全部 `result=pass` 但 `checkpoint ok=false` 并被 06-testdemo.json 判 `status=partial`：
+
+1. `case_F_01_02` cp=4：`fren.exists() && !fdst.exists()`——`fdst` 执行 `renameTo` 后指向新路径仍 exists。修：用 `Poco::File(dst)` 独立对象断言。依据 `Poco::File::renameTo` 文档（对象路径就地更新）。
+2. `case_F_01_05` cp=3：`parsed.timestamp() - ts` 差 28799917221μs。修：扣除 `tzd`（parse 回传）。依据 `DateTimeParser::parse` 返回 UTC + tzd 语义。
+3. `case_F_01_09` cp=0：`re.match("date: 2026-09-12 ok")` false。修：`re.match(input, mpos)` 带 pos 重载。依据 `RegularExpression::match` 全串锚定 + `extract` 部分搜索语义。
+4. `case_F_06_02` cp=1,2：`IF NOT EXISTS` + 重跑插两轮 → rows=4。修：setup 先 `DROP TABLE IF EXISTS`。依据 SQLite 建表语义（表已存在则不重建、数据保留）。
+5. `case_F_08_01` cp=1：20B 文件压缩后 142B。修：测试数据改 1000B+。依据 ZIP 格式本地文件头/中央目录开销（~100B+）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L033.md

@@ -0,0 +1,93 @@
+<!-- 来源：new/PC（某国密 OpenSSL 分支 8.5.0-pre2 测试线阶段 6 实证） | 原编号 E156 --> 一句话定位：demo 验证阶段（`napi_stub.cpp`）给 TLS/NTLS/密码学 API 接线时五类典型错——TLS 1.3 内存 BIO 握手用「泵模式」信号乱序、NTLS 漏调 `SSL_CTX_enable_ntls()`、SM2 证书走 `X509_sign` legacy ameth 空指针、DRBG 构造缺 CIPHER 参数直接 instantiate（根因表述 2026-09-21 由 E177 修正）、CA 自签证书缺 `basicConstraints CA:TRUE`——症状全长得像「库 bug」，实为 **harness 接线错（harness-defect）**，改 demo stub 不改库。
+
+# L033: demo 验证接线错——TLS/NTLS/密码学 API 握手与证书构造（harness-defect）
+
+> **严重度**: 2 major | **领域**: test/contract + tls/ntls/crypto | **自动修复**: none（改 demo stub，不动库；依据回指 OpenSSL/该分支头文件与官方测试模式）
+
+---
+
+## 问题现象
+
+demo 验证阶段（`napi_stub.cpp` 接线）给 OpenSSL 系/某国密 OpenSSL 分支密码库接线时，五类典型症状，共同点是**报在 stub 侧、根因在 stub 侧**，库本身没错——与 E149/E155 同门（harness-defect），属**密码学握手/证书构造**新亚类：
+
+1. **TLS 1.3 内存 BIO 握手失败（client 报 unexpected message）**：
+
+```
+OHPTCASE: result=fail id=F-04-01 detail=TEST F-04-01: FAILED at checkpoint 2
+hilog: mem_bio_handshake client: error:0A0000F4:SSL routines::unexpected message
+```
+
+2. **NTLS（国密 TLCP）握手报 unsupported SSL version**：
+
+```
+OHPTCASE: result=fail id=F-06-01
+hilog: client: error:0A0000F4:... SSL_R_UNSUPPORTED_SSL_VERSION（legacy_version=0x0101）
+```
+
+3. **SM2 自签证书生成失败（X509_sign 空参数）**：
+
+```
+hilog: sm2 X509_sign: error:078C0102:common libcrypto routines::passed a null parameter
+```
+
+4. **DRBG 确定性随机数用例全挂（实例化失败）**：
+
+```
+OHPTCASE: result=fail id=F-07-02 cp=0 ok=0 expect=DRBG 实例创建成功 actual=失败
+```
+
+5. **X.509 证书链验证对正确 CA 也失败（invalid CA）**：
+
+```
+OHPTCASE: result=fail id=F-08-01 cp=5 ok=0 expect=证书链验证通过 actual=失败
+hilog: X509_V_ERR_INVALID_CA（v3 CA 无 basicConstraints CA:TRUE）
+```
+
+## 根因
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| 1 | TLS 1.3 握手 client 报 `SSL_R_UNEXPECTED_MESSAGE` | 握手驱动用「泵模式」（`SSL_do_handshake` 交替 + `BIO_read/BIO_write` 手动搬数据 + `BIO_set_mem_eof_return`）。对 TLS 1.2 兼容、对 **TLS 1.3 信号乱序**（1.3 握手消息加密、时序依赖严格，手工泵破坏消息顺序） | 用 **ssltestlib 交叉接线**（`create_bare_ssl_connection` 模式）：client/server 各挂**分离的读/写 mem BIO**，且把对端的读 BIO 接到本端的写 BIO（共享 BIO 用 `BIO_up_ref` 增持后再交给第二个 SSL，否则 `SSL_free` 双重释放——上轮启动崩溃根因）；`SSL_connect`/`SSL_accept` 交替驱动，**无 pump**。OpenSSL 官方 `sslapitest`/该分支 `ssl_ntls_api_test` 均用此模式 |
+| 2 | NTLS 握手报 `SSL_R_UNSUPPORTED_SSL_VERSION`（legacy_version=0x0101） | **漏调 `SSL_CTX_enable_ntls()`**。该分支 `ssl/statem/statem.c` 的 `ossl_statem_connect/accept` 只在 `sc->enable_ntls==1` 时路由到 `state_machine_ntls()`（NTLS 状态机）；否则即使 `NTLS_method()` 也走标准 TLS 状态机，用 NTLS_VERSION=0x0101 协商 → 对端（TLS）不认 0x0101 | **sctx 和 cctx 都要显式 `SSL_CTX_enable_ntls()`**（在 `SSL_new` 之前）。官方 `ssl_ntls_api_test.c` 每个用例都是 `NTLS_method()` + `SSL_CTX_enable_ntls()` 成对调用。构建开关 `enable-ntls`（见 pc-knowledge-base OpenSSL 系文档 §3）只是把符号编进去，**运行时仍要显式启用** |
+| 3 | SM2 `X509_sign` 报 `ERR_R_PASSED_NULL_PARAMETER` | 该分支 8.5.0-pre2 的 `X509_sign`（`ASN1_item_sign` 路径）对 **provider-native SM2 密钥走 legacy ameth 兼容层时传 NULL**（兼容缺口）。F-05-01（`EVP_DigestSign` SM2+SM3 签名）通过证明 SM2 签名能力本身完好 | **用 PEM 预生成证书嵌入代码**，`PEM_read_bio_X509`/`PEM_read_bio_PrivateKey` 加载，绕开 `X509_sign` 路径（该分支官方 `ssl_ntls_api_test.c` 用 `test/certs/sm2/` 预生成证书同款做法）。宿主 OpenSSL 3.5.6 可编出（`openssl ecparam -name SM2 -genkey` + `req -new -x509 -sm2`） |
+| 4 | DRBG `EVP_RAND_instantiate` 失败 | **（2026-09-21 修正，原「无 parent 沙箱无熵源可种」表述不成立）真根因：CTR-DRBG ctx 创建后未设 CIPHER 参数**——`drbg_ctr_new` 只置 `use_df=1`，`cipher_ecb` 为空使 instantiate 静默 return 0（`error:1C8000BC` 仅包装层、无内层错误、child_strength=0）。设备诊断 `parent=CTR-DRBG` 实证换父源/换熵源无效 | 创建后**必须 `EVP_RAND_CTX_set_params(CIPHER=AES-256-CTR)`** 再 instantiate（生产链 `rand_new_drbg` 同款），父源生产用法用 `RAND_get0_private`。`OSSL_RAND_PARAM_TEST_ENTROPY`/`TEST_NONCE` 只被 test-only 的 TEST-RAND provider 消费——「同种子确定性」非生产 API 契约。完整根因链与指纹 → 见 **E177** |
+| 5 | `X509_verify_cert` 对 v3 CA 报 `X509_V_ERR_INVALID_CA` | 自签 CA 证书 `X509_set_version(cert, 2)` 升 v3 后**未设 `basicConstraints` 扩展**——OpenSSL 3.x 对 v3 无 `CA:TRUE` 的证书 `X509_check_ca` 返回 0 → 拒绝认其为 CA | `generate_self_signed_rsa_cert` 在 `X509_sign` **之前**加扩展：`X509V3_EXT_conf_nid(NULL, &v3ctx, NID_basic_constraints, "critical,CA:TRUE")` + `X509_add_ext`（签名覆盖全部扩展，必须 sign 前加） |
+
+**不变量**：与 E149/E155 一致——五类都属于「改测试侧不改库」的 harness-defect，修 `napi_stub.cpp` 接线，依据必须给得出 `file:line` 且真在盘（回指 OpenSSL/该分支源码 `ssl/statem/statem.c`、`test/rand_test.c`、`test/ssl_ntls_api_test.c` 语义），不触碰库的任何返回码契约。
+
+## 判别方法
+
+1. 报错点在 **demo stub（napi_stub.cpp）** 内部，不在库函数入口；
+2. 等价能力已在**同库其他路径**验证过：同一设备上 `test_large_message_tls` rc=0（03-adapt 设备日志）→ TLS 1.3 握手能力在，是 demo 接线问题；`F-05-01` SM2+SM3 签名通过 → SM2 能力在，是 `X509_sign` 接线路径问题；
+3. 官方测试（`sslapitest`/`ssl_ntls_api_test`/`rand_test`）存在**同款构造模式**可对照（交叉接线 / `enable_ntls` 成对 / PEM 预生成 / TEST-RAND parent / basicConstraints）。
+
+三条全中 → 归因 harness-defect，改 stub，不是库 bug。
+
+## 解决方案
+
+1. **TLS 1.3 内存 BIO 握手**：照抄 ssltestlib `create_bare_ssl_connection` 的交叉接线：分离读写 BIO + 对端读连本端写 + `BIO_up_ref` 增持共享 BIO（**漏 up_ref 会双重释放、`SSL_free` 时启动崩溃**）+ `SSL_connect`/`SSL_accept` 交替驱动。不要用手工 `pump_bio` 泵 TLS 1.3。
+2. **NTLS 握手**：`NTLS_method()` 与 `SSL_CTX_enable_ntls()` **成对**调用（sctx 和 cctx 都要，且先于 `SSL_new`）。`SSL_CTX_set_verify` 也必须在 `SSL_new` 之前（SSL 创建时继承 ctx verify 模式）。
+3. **SM2 证书**：不调 `X509_sign`，PEM 预生成证书 `PEM_read_bio_*` 加载（宿主 OpenSSL 3.5.6 可编；注意 SM2 私钥加载后 `EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)`）。
+4. **DRBG 显式实例化**：创建后先 `EVP_RAND_CTX_set_params(CIPHER=AES-256-CTR)`（承重参数，漏了 instantiate 必挂 E177）；生产契约父源用 `RAND_get0_private`。确定性断言只有 TEST-RAND provider 可达（test-only），用例设计别钉它。
+5. **v3 CA 证书**：`X509_sign` 之前 `X509V3_EXT_conf_nid(NID_basic_constraints, "critical,CA:TRUE")` 加扩展。
+
+## 影响范围
+
+所有「demo 验证阶段给 OpenSSL 系 / 某国密 OpenSSL 分支 / 其他国密分支密码库接线」的场景。高频于：TLS 1.3 内存握手、NTLS/TLCP 双证书、SM2/SM3 国密、DRBG/随机数、X.509 链验证。OpenSSL 系普遍适用（交叉接线与 basicConstraints 是 OpenSSL 3.x 通用语义），`enable_ntls` 与 SM2 ameth 缺口是某国密 OpenSSL 分支特有。
+
+## 关联
+
+- E149 / E155：demo 接线 harness-defect 同门（音频参数类 / 语义理解类；分界见各条）
+- E139：assertion/参数类型 testcase-defect（改用例预期；与 harness-defect 分界见 E155）
+- `pc-knowledge-base/adaptation/鸿蒙PC-OpenSSL系密码库交叉编译.md` —— 构建开关 `enable-ntls`、TLS 内存握手需自签证书（本条目是运行时接线侧补充）
+- `pc-knowledge-base/platform/鸿蒙PC-app域测试前置条件矩阵.md` —— app 域 socketpair(AF_UNIX) 可用（socket BIO 备选路径）
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2 测试线 demo 验证（2026-09-14，HAD-W32 / OpenHarmony-6.1.1.135 / aarch64），19 条用例三轮从 15/19 → 16/19 → 18/19 → 19/19：
+
+1. `case_F_04_01`（TLS 1.3 内存 BIO 握手）：泵模式 `SSL_R_UNEXPECTED_MESSAGE` → 交叉接线 + `BIO_up_ref` 修复通过。依据 `source/test/sslapitest.c` 的 `create_bare_ssl_connection`。
+2. `case_F_04_02`（TLS 1.3 证书验证）：同交叉接线 + `SSL_CTX_set_verify` 移到 `SSL_new` 前修复通过。
+3. `case_F_06_01`（NTLS 双证书）：SM2 `X509_sign` ameth 空参 → 官方 `test/certs/sm2/` PEM 证书嵌入加载 + **显式 `SSL_CTX_enable_ntls()`（sctx+cctx）** 通过，密码套件 `ECC-SM2-SM4-CBC-SM3`。依据 `source/test/ssl_ntls_api_test.c`（`NTLS_method()`+`enable_ntls` 成对）与 `source/ssl/statem/statem.c`（`enable_ntls==1` 才路由 NTLS 状态机）。
+4. `case_F_07_02`（DRBG 确定性）：TEST-RAND parent + `OSSL_RAND_PARAM_STRENGTH=256` + 固定熵通过。依据 `source/test/rand_test.c`。（**2026-09-21 修正**：该配方当时能过的承重参数是 CIPHER——`rand_test.c` 同款设了 `OSSL_DRBG_PARAM_CIPHER`，本文原根因表述「无 parent 无熵源」不成立；完整根因链、1C8000BC 指纹与生产契约接线见 E177）
+5. `case_F_08_01`（X.509 链验证）：`generate_self_signed_rsa_cert` 加 `basicConstraints critical,CA:TRUE` 通过。依据 OpenSSL 3.x `X509_check_ca` 语义。