失败与副作用矩阵¶
本页逐公共入口列出读写、spawn、Git、网络、残余状态与稳定错误码。它服务于调用方在接入前判断风险,并作为 capability-catalog.json 中 sideEffects 与 failureSemantics 字段的人类可读投影。所有事实以真实实现与负例测试为准。
符号约定:读=读取文件系统;写=写入文件系统;spawn=启动子进程;Git=读写 Git;网络=访问远端;残余=调用结束后仍留在磁盘/进程中的状态。
Contracts(纯函数层)¶
| 入口 | 读 | 写 | spawn | Git | 网络 | 残余状态 | 稳定错误码 |
|---|---|---|---|---|---|---|---|
validateDocument |
否 | 否 | 否 | 否 | 否 | 无(编译缓存仅驻留内存) | SFC1001/SFC1002/SFC1006 |
compileSchema / detectDialect |
否 | 否 | 否 | 否 | 否 | 无 | SFC1006/SFC1012 |
loadRegistry / findSchemaByObject / findProtocol |
否 | 否 | 否 | 否 | 否 | 无 | SFC1003/SFC1004 |
runChecks / collectUnresolvedRefs |
否 | 否 | 否 | 否 | 否 | 无 | SFC1002–SFC1010 |
verifyAllFixtures / verifyFixture |
否 | 否 | 否 | 否 | 否 | 无 | SFC1010 |
ERROR_CODES / stableError |
否 | 否 | 否 | 否 | 否 | 无 | 冻结登记表,不新增 |
Contracts 全部为纯函数,无文件/Git/网络/进程副作用;错误对象含 stableError 与 details.kind,便于调用方分类。
Harness(机制层,受收容)¶
| 入口 | 读 | 写 | spawn | Git | 网络 | 残余状态 | 稳定错误码 |
|---|---|---|---|---|---|---|---|
validateContractDocument |
否 | 否 | 否 | 否 | 否 | 无(校验器缓存内存) | SFC 校验失败 |
resolveContained / readFileContained |
是(只读) | 否 | 否 | 否 | 否 | 无 | SFC2004(path-traversal/symlink-escape/realpath-escape) |
writeFileAtomic |
否 | 是(受收容) | 否 | 否 | 否 | 失败回滚临时文件 | SFC2004(atomic-write-failed) |
TemporaryWorkspace / withTemporaryWorkspace |
否 | 是(临时目录) | 否 | 否 | 否 | 退出时清理临时目录 | SFC2004(workspace-disposed) |
computeResourceClosure / digestBytes |
否 | 否 | 否 | 否 | 否 | 无 | SFC(声明/内容违规) |
parseRequest / processRequest |
否 | 否 | 否 | 否 | 否 | 无(纯函数管线) | SFC2004 |
validateReportModel / renderReportMarkdown / buildBinding / checkReport |
否 | 否 | 否 | 否 | 否 | 无(纯函数) | SFC3001/SFC3002/SFC3003 |
buildAdapterClosure / verifyAdapterBuildManifest |
否 | 否 | 否 | 否 | 否 | 无 | SFC2004(missing-resource) |
materializeAdapterBuild |
否 | 是(受收容,sibling + rename) | 否 | 否 | 否 | 无(原子 rename) | SFC2004 |
probeVersionVector |
否 | 否 | 默认否(需显式 --allow-host-spawn) |
否 | 否 | 无 | SFC2004 |
openStateStore / appendEvent / readEvents / writeSnapshot |
是 | 是(事件/快照/锁文件) | 否 | 否 | 否 | 事件日志 + 锁文件 | SFC2004(store-locked/链断裂) |
inspectStateStoreLock / recoverStateStoreLock |
是 | 是(仅恢复写锁) | 否 | 否 | 否 | 锁文件(单调 fencing) | SFC2004 |
runMechanismCliBatch / mechanisms-cli.mjs --batch(since 0.19.0,candidate) |
否 | 否 | 否 | 否 | 否 | 无(只写调用方提供的 output/error 流) | 退出码 0(全成功)/ 2(至少一项失败或整批拒绝);details.kind 封闭为 batch-structure-invalid/batch-item-limit/batch-input-limit/batch-output-limit |
applyFileSet / recoverFileSet / pruneFileSetRecovery(since 0.21.0,candidate) |
是(受收容只读;含恢复材料与根绑定复核) | 是(业务目标严格发布/原子替换 + 根内固定 .foundation-file-apply 材料) |
否 | 否 | 否 | 恢复材料(journal 与 operations/<id>/{before,after}/<index>)默认保留,只有显式 prune 清理已终结操作的材料 |
可捕获失败返回 file-set-result;外码沿用 SFC2004,details.kind 与 details.phase 为闭枚举,outcome/paths/materials 报告逐路径事实 |
文件集合入口同样按失败阶段决定可观察副作用。整组前检失败、环境不支持与容量越限在任何业务写入前返回,业务零写入;领域验证返回 false、抛错、超时或非法结果会触发自动恢复,验证状态与恢复状态分开报告;恢复遇冲突路径保留外部内容并继续其他安全项;有效提交事件决定不再回滚,目标复核或持久化未确认时报告 commit-unconfirmed 并保留材料。未为该路径写入持久 apply-intent 事实前不触碰业务路径,也不承诺瞬时多文件可见性,更不抵御不合作的并发写者;恢复要求调用方先建立排他维护区间,清理在无残留时直接取得正常 writer,只在需要故障接管时才要求同一维护前提。
批量入口的失败阶段决定可观察副作用。请求字节、输入项数或结构的预检拒绝不会调用机制,stdout 为空;输出容量只能在当前项返回后确认,因此该项可能已经执行,但后续项不会再执行,stdout 仍为空。输出通道失败时可能已有部分字节送出,整体退出 2;若错误通道也失败,错误对象不保证能够交付。
Harness 的 HARNESS_EXCLUSIONS 明确排除 release-state、remote-network-access、business-semantics、workflow-orchestration、model-calls、git-writes。
Engineering Kit(工程命令层)¶
| 入口 | 读 | 写 | spawn | Git | 网络 | 残余状态 | 稳定错误码 / 退出码 |
|---|---|---|---|---|---|---|---|
scaffoldTarget |
否 | 是(受收容骨架,原子 + 收容) | 否 | 否 | 否 | 无(失败不留半成品) | SFC2004(target-not-empty) |
planAdoption |
是 | 否 | 默认可能(冻结只读 git status;可关闭) | 只读探测 | 否 | 无(stdout 输出) | SFC 完成判定 false |
buildProfileDraft |
否 | 否 | 否 | 否 | 否 | 无(stdout 输出) | SFC 完成判定 false |
runProjection |
是(读 manifest) | 是(受管路径,两阶段) | 否 | 否 | 否 | 无(失败零写/回滚) | SFC2004(unauthorized-path/handwritten-overwrite/conflict-drift) |
runChecks(check) |
是 | 否 | 默认可能(冻结只读 git status;可用 --no-git-spawn 关闭) |
只读白名单 | 否 | 无 | 退出码 1(发现)/ 2(机制) |
runChecks(declared version) |
是(只读声明引用) | 否 | 否 | 否 | 否 | 无 | 退出码 1(发现)/ 2(机制) |
runEntryContractCheck(legacy / declared) |
是 | 否 | 否 | 否 | 否 | 无 | 退出码 1(发现)/ 2(机制) |
runCommand("check") / checkEntriesAction + conclusionOutput |
是 | 是(已存在输出根内独占创建一个文件) | 否 | 否 | 否 | 成功后保留结论文件;冲突时零覆盖 | 退出码 0/1/2;结构失败 SFC1001,发布失败 SFC2004 |
check relock |
是 | 是(显式受控写) | 否 | 否 | 否 | 受控 relock 事务状态 | 退出码 0/1/2 |
check qualification / runQualification |
读取 request 与 bindings | 在调用方绑定根下写私有证据 | 是,预检通过后 | 否 | 绑定的 executable 仍可能联网 | 终态不确定时保留证据 | 退出码 0/1/2;四态结果 |
runPluginVerification |
是(调用方绑定根) | 是(fresh workspace、宿主状态、私有证据) | 是,仅本地 executable | 否 | 绑定的 executable 仍可能联网 | 不确定证据会保留 | 四态 plugin-verification-result |
runSkillFamilyDirectoryVerification |
是(调用方绑定根) | 是(私有 raw evidence) | 是,仅本地 executable | 否 | 绑定的 executable 仍可能联网 | 不确定证据会保留 | 四态目录结果 |
renderReportAction / checkReportAction |
是 | 仅 --out/--binding |
否 | 否 | 否 | 默认只写 stdout | SFC3001/SFC3002/SFC3003 |
probeGitState / probeGitFacts |
是 | 否 | 默认可能(冻结只读 Git 子进程;可关闭) | 只读白名单 | 否 | 无 | SFC(越权参数拒绝) |
describeHost / resolveHostId / probeHost / buildHostAdapter / planHost / applyHostPlan |
是 | build/install/update 写(受收容;uninstall 不写) | probe 默认否 | 否 | 否 | 仅显式 authorizationRef |
SFC2004;远端 apply 与删除式 uninstall 稳定拒绝 |
loadLicensingProfile / generateLicenseContent 等 |
否 | 否(纯函数生成) | 否 | 否 | 否 | 无 | SFC(非法 Profile) |
checkIdentityDrift / validateIdentityAgainstProfile |
是 | 否 | 否 | 否 | 否 | 无 | findings |
cliMain / runCommand |
依子动作 | 依子动作 | 依子动作 | 依子动作 | 绑定 executable 可能联网 | 依子动作 | 退出码 0/1/2 |
Kit 的 FORBIDDEN_SIDE_EFFECTS 含 git-init/commit/push/tag、publish、remote-write;REFUSED_MUTATION_FLAGS(含 --apply)在 CLI 入口即拒。
Foundation 本身不发起网络请求,但绑定的 executable 仍可能联网。Foundation 不提供 sandbox 或 egress 阻断,调用方与运行环境负责隔离。Qoder、WorkBuddy 与 Kimi 入口仍为 manual/candidate;受控 fixture 只证明生产接线,不授予真实宿主资格。
残余状态合集¶
- 原子写:失败时回滚临时文件,目标目录不留半成品。
- 临时工作区:退出(含异常路径)时清理。
- 状态存储:事件日志是唯一权威,snapshot 为派生缓存;崩溃遗留锁需调用方在 Foundation 外确认旧写者终止后显式恢复,不自动偷锁。
- 文件集合:恢复材料默认保留在业务根内固定
.foundation-file-apply下,只有显式 prune 清理精确的已终结操作且保留 journal;未终结与冲突项的材料不清理。机制不按后缀删除未知邻接暂存文件,只报告possible-unknown。 - 投影:任一校验失败整体拒绝、零写入;覆盖既有文件需声明
expect.sha256前置状态。 - adopt-plan、普通 runChecks 与普通 check:结构性只读且不写文件;默认可能启动一条冻结参数的只读 Git status 子进程,可由
--no-git-spawn(或 API 的allowGitSpawn: false)关闭,运行前后字节级零变化。check relock 与 check qualification 的副作用见上表。 - declared 分支的
runChecks与runEntryContractCheck不探测 Git、不执行目标,也不写文件。只有两个既有包装入口在conclusionOutput完整明确时独占创建结论文件。
失败后调用方该做什么¶
- 校验失败(
SFC1001/SFC2002/SFC2003):检查输入是否满足目标 Schema 或参数合同,不重试已被冻结拒绝的登记。 - 收容失败(
SFC2004+path-traversal等):确认根目录与路径是否越界,不要把业务选择规则塞进 Foundation。 - 状态锁冲突(
store-locked):在 Foundation 之外确认旧写者已终止,再用精确匹配的 owner/fencing 调用恢复。 - check 发现(退出码 1):处置发现项,Kit 不自动修复。
Windows 失败与残余¶
固定世代读取(resolveFixedSetGeneration)为只读操作,发布(publishFixedSetGeneration)写入指针并保留所有世代。提交前可确认失败,提交后或不确定状态需分开报告。失败与副作用可能产生同父暂存,但不按文件后缀清未知文件。文件集合整组还原能力前检失败时,不产生业务写入,但机制材料仍需按结果判断。
apply 后验证失败时,按记录恢复,不自动偷锁。Job Object 强杀完成需满足零活动进程、流收尾与全部句柄关闭。刷新仅请求,不保证断电事务。调用者应按结果中的提交、恢复与残余事实决定后续动作,不把不确定状态当成可以安全重试。