English

帮助与分诊¶

本页按错误码、进程退出码与现象给分诊路径。Foundation 的错误码体系冻结在 Contracts（src/error-codes.json），不漂移；机制失败统一为 SFC2004 加稳定 details.kind。

按稳定错误码分诊¶

错误码	名称	含义	处置
SFC1001	SCHEMA_VALIDATION_FAILED	文档未通过目标 Schema 验证	检查文档必填字段与类型约束
SFC1002	UNKNOWN_SCHEMA_ID	`$id` 未在登记表注册	确认 `$id` 拼写与 Contracts 版本
SFC1003	DUPLICATE_SCHEMA_ID	重复 `$id` 注册被拒	不重复注册，复用已有登记
SFC1004	DUPLICATE_PROTOCOL_NAME	重复协议名/版本被拒	不重复登记协议
SFC1005	UNRESOLVED_REF	`$ref` 目标无法解析	检查 `$ref` 指向
SFC1006	UNSUPPORTED_DIALECT	方言不在支持集	仅用 draft-07 / 2020-12
SFC1007	UNKNOWN_CHECK_TYPE	规则用九类外检查类型	不自定义检查类型
SFC1008	RULE_BUDGET_EXCEEDED	强制规则超预算/上限	不超 20（绝对 30）
SFC1009	UNKNOWN_ERROR_CODE	引用未登记错误码	只引用冻结登记表
SFC1010	FIXTURE_EXPECTATION_MISMATCH	fixture 行为与期望不符	查 fixture 声明
SFC1011	UNKNOWN_PROTOCOL	引用未登记协议	确认协议名/版本
SFC1012	SCHEMA_COMPILE_FAILED	Schema 本身无法编译	查 Schema 语法
SFC2002	UNKNOWN_OPERATION	操作名不在冻结词汇表	只用 `validate`
SFC2003	INVALID_PARAMS	参数不满足 params 合同	检查参数
SFC2004	EXECUTION_FAILED	机制执行失败	看 `details.kind` 细分
SFC3001	REPORT_DIGEST_MISMATCH	报告/结果摘要与绑定不一致	重算 model/result
SFC3002	REPORT_ELEMENT_MISSING	报告缺强制元素	补全报告字段
SFC3003	REPORT_FACT_DRIFT	报告字节偏离确定性重渲染	用机器结果重渲染

校验一直报 SFC1002：$id 未注册，先确认 Contracts 版本与 $id 命名空间。
路径操作报 SFC2004 + path-traversal/symlink-escape/realpath-escape：路径越出受收容根，确认根目录边界，不要把业务选择规则塞进 Foundation。
原子写报 SFC2004 + atomic-write-failed：目标越界或内容类型非法，检查路径收容与内容类型。
状态存储报 store-locked：旧写者可能仍持有锁；在 Foundation 外确认旧写者已终止，再用精确 owner/fencing 调用 recoverStateStoreLock。
CLI host apply 直接失败：Engineering Kit 的 adopt-plan host-apply、通用或远端 apply 仍稳定拒绝。包 API applyHostPlan 只执行已登记宿主的摘要绑定本地 install/update；执行 uninstall 计划会返回 manual-recovery-required，不删除文件。Qoder 完整 driver 仍为 unsupported。
同级 adapter 验证失败：verifyHostPeers 只接受由已登记 Profile 证明的宿主和路径类别；任一 peer 的路径、闭包、字节或 logicalMappings 不一致都会失败关闭，不会授予安装或发布状态。
文档版本/命令对不上真源：以 scripts/docs/fact-check.mjs 复算结果为准，不凭记忆修订。

Engineering Kit 只有四个顶层命令：scaffold、adopt-plan、projection、check。其中 check 只诊断不修复，发现项交调用方处置。