跳转至

English

失败与副作用矩阵

本页逐公共入口列出读写、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 强杀完成需满足零活动进程、流收尾与全部句柄关闭。刷新仅请求,不保证断电事务。调用者应按结果中的提交、恢复与残余事实决定后续动作,不把不确定状态当成可以安全重试。