跳转至

skill-family-harness-node 公共 API 参考

本页从真实导出(src/index.mjs 与各源模块)核对,不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明:签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 details.kind、前置条件与信任锚、since 与 stability、源文件与正例/负例测试、调用方仍拥有的业务语义。

Harness 是薄运行时:消费 Contracts,只实现业务中立机制;不拥有业务语义、编排、Git、网络与第二语言。包级常量:HARNESS_CAPABILITIES(22 项能力,闭集)、HARNESS_EXCLUSIONS(明确排除 business-semantics / workflow-orchestration / git-writes / model-calls / release-state / remote-network-access)。

能力分组(与 docs/agents/capability-catalog.json 对应):


契约校验 (foundation.harness.contract-validation)

validateContractDocument / getValidator / resolveSchemaContext / validatorCacheSize

  • 签名:
  • validateContractDocument(document, { schemaId, dialect, policy = "strict" } = {})
  • getValidator({ schemaId, dialect, policy = "strict" } = {})
  • resolveSchemaContext({ schemaId, dialect, policy = "strict" } = {})
  • validatorCacheSize()
  • 输入:schema 上下文或契约文档。
  • 输出:校验结果(语义同 Contracts validateDocument,但经 Node 运行时复用缓存);缓存大小查询。
  • 纯函数:否(getValidator / validateContractDocument 写入进程内以 schema 为键的校验器缓存)。
  • 副作用:进程内内存缓存校验器实例;无文件/Git/网络。
  • 稳定错误码与 details.kind:沿用 Contracts SFC1001 / SFC1002 / SFC1006;底层机制失败统一 SFC2004 + HARNESS_ERROR_KINDS 的 kind(如 INVALID_PATH)。
  • 前置条件与信任锚:已安装 skill-family-contracts;Ajv 8.20.0。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/validation.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/validation.test.mjs。
  • 调用方仍拥有的业务语义:契约业务字段语义(语义定义仍在 Contracts)。

路径收容 (foundation.harness.path-containment)

classifyPathInput / resolveContained / readFileContained

  • 签名:
  • classifyPathInput(input, platform = process.platform)
  • resolveContained(root, relPath)
  • readFileContained(root, relPath, { encoding } = {})
  • 输入:根目录(收容边界)与待解析的相对/绝对路径。
  • 输出:受收容绝对路径或读到的文件内容。
  • 纯函数:classifyPathInput 是;resolveContained / readFileContained 为 async,含只读文件系统访问。
  • 副作用:只读文件系统访问(读取/解析);不写。
  • 稳定错误码与 details.kind:机制失败抛 HarnessError(SFC2004)+ details.kind ∈ {PATH_TRAVERSAL, SYMLINK_ESCAPE, REALPATH_ESCAPE, INVALID_ROOT, ABSOLUTE_PATH, WINDOWS_DRIVE_PATH, WINDOWS_PATH, UNC_PATH, INVALID_PATH, READ_FAILED}。
  • 前置条件与信任锚:调用方提供明确根目录;所有解析结果必须落在根目录内;Windows 盘符/UNC 逃逸同样拒绝。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/paths.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/containment.test.mjs、boundaries.test.mjs。
  • 调用方仍拥有的业务语义:哪些路径是业务允许的选择规则(业务选择语义留在调用方)。

严格读取 (foundation.harness.strict-read)

readFileStrict

  • 签名:readFileStrict(root, relPath, { encoding?, expectedSha256? } = {})(async)。
  • 输入:收容根目录、相对文件路径,可选的 utf8 编码与小写 sha256 预期摘要。
  • 输出:冻结回执 { path, content, sha256, bytes, mode }。指定 utf8 时,content 是字符串;省略编码时,content 是 Buffer。
  • 纯函数:否,函数只读一个受收容的普通文件。
  • 副作用:执行 lstat、open、read 与文件身份复核;不写文件,不访问 Git 或网络。
  • 稳定错误码与 details.kind:失败使用 SFC2004。缺失文件返回 missing-resource,摘要不符返回 content-guard-rejected,目录返回 read-failed,越界路径沿用路径收容的失败种类。
  • 符号链接边界:叶节点符号链接始终拒绝。祖先目录可以是指向根内目录的符号链接;其规范路径仍须受 root 收容。
  • 前置条件与信任锚:expectedSha256 的来源与信任由调用方负责;摘要只覆盖实际读到的字节。
  • since / stability:0.6.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/strict-read.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/strict-read.test.mjs。
  • 调用方仍拥有的业务语义:选择哪个权威文件、摘要从何而来,以及读取失败后的处置。

身份绑定读取 (foundation.harness.bound-read)

createFilesystemRootBinding / readFileBound

  • 签名:createFilesystemRootBinding(root);readFileBound(root, relPath, { rootBinding, encoding?, expectedSha256? } = {})(均为 async)。
  • 输入:已规范化的绝对真实目录、受收容的相对 POSIX 路径,以及调用方先前批准的冻结根绑定。encoding 仅支持 utf8;权威读取可带小写 sha256 预期摘要。
  • 输出:根绑定为冻结可序列化值;读取回执为冻结 { path, content, sha256, bytes, mode, statMode }。mode 保持旧兼容含义(st_mode & 0o777);statMode 是同次原生打开描述符 fstat 得到的完整 POSIX st_mode,包括文件类型与特殊权限位。
  • 语义边界:以下 POSIX v1 描述保持;Windows 分支见页末。根与中间目录由固定四平台 N-API 闭包以不跟随符号链接的句柄相对方式获取;叶子必须是单链接普通文件。句柄不会逃逸,调用结束前关闭。绑定读取不提供删除或恢复状态机。
  • 副作用:只读文件系统访问;不写文件、不触 Git、网络或进程。
  • 错误:根身份不符、符号链接组件、缺失资源和摘要不符均失败关闭;不支持的 Darwin/Linux 架构不提供 JavaScript 回退。
  • since / stability:0.9.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/bound-read.mjs 与 src/native/。
  • 正例/负例测试:packages/skill-family-harness-node/test/bound-read.test.mjs。

完整树观察 (foundation.harness.filesystem-tree-observation)

observeFilesystemTree

  • 签名:observeFilesystemTree({ root, rootBinding, symlinkPolicy?: { mode: "reject" | "record" } })(async)。调用方先用既有 createFilesystemRootBinding 批准根目录。
  • 输入:已规范化的真实绝对目录及其根绑定。每次调用重新读取目录和普通文件,空树合法。
  • POSIX v1 输出(Windows v2 见页末):私有 filesystem-tree-observation,含按路径排序的完整成员、根绑定和 membersDigest。文件成员包含同次读取的 contentBase64、sha256、bytes 与完整 POSIX statMode;目录成员只含路径、类型和模式,不伪造文件摘要。省略 symlinkPolicy 或使用 reject 时保持 0.14 的 UTF-16 关系顺序和既有原生语义;record 在稳定、调用方隔离且无并发 namespace writer 的本地树上走 Node/JS 分支,使用 Unicode 码点顺序,记录 symlink 自身的 targetBase64、bytes、statMode,绝不读取或递归 target。membersDigest 按所选模式的成员顺序推导。
  • 副作用:只读文件系统,不安装、不启动进程、不访问网络。结果含原始文件内容,调用方必须保护敏感数据。
  • 失败语义:参数不合法抛 TypeError,机制失败沿 SFC2004 关闭,不把部分观察报告为成功。record 检测到观察期间的漂移即失败关闭,普通文件复用 readFileBound,硬链接与特殊文件继续拒绝。
  • 保证边界:每次检查同一根绑定,不使用旧缓存;record 是 best-effort candidate,不承诺事务快照、同 UID 恶意并发或 ABA 安全。消费者负责在宿主命令完成后调用,并保留 npm .bin 等领域接受规则;真实恶意并发威胁应交回 Foundation,不在本地复制 walker、native addon、Harness、schema、Registry、runner 或 receipt 链。
  • since / stability:0.13.0 / candidate。观察完成不等于消费者接受载荷。
  • 源文件:packages/skill-family-harness-node/src/filesystem-observation.mjs 与 src/native/bound_read.c。
  • 正例/负例:packages/skill-family-engineering-kit/test/plugin-verification.test.mjs 的实际树观察与载荷政策组合测试。

可执行身份观察 (foundation.harness.executable-identity-observation)

observeExecutableIdentity

  • 签名:observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })(async)。
  • 输入:调用方提供的非重叠真实根绑定、绝对路径或显式 pathEntries 查找,以及可选的显式解释器根策略;不读取 ambient PATH。
  • 输出:逐次只读的可执行入口观察,含 canonicalEntry、symlinkChain、sha256、bytes、statMode、entryKind、解释器与 launch 计划。/usr/bin/env shebang 通过显式 pathEntries 找到解释器时,解释器观察保留候选入口的完整 symlink chain,不折叠成最终文件。
  • 副作用:只读 lstat / readlink 与既有 readFileBound;不启动进程、不写文件、不使用跨调用缓存。
  • 失败语义:路径越界、符号链接漂移或循环、非单链接可执行普通文件、解释器策略不符及字节变化均失败关闭;不返回部分身份结果。
  • 保证边界:这是逐次点时观察,调用方必须在正式启动前紧邻重观察。它不证明 wrapper 控制流、ambient PATH、fd-exec、内核最终映像、签名信任、跨调用连续身份、宿主支持/生命周期或领域接受。
  • since / stability:0.15.0 / candidate。观察完成不等于宿主资格或启动授权。
  • 源文件:packages/skill-family-harness-node/src/executable-identity.mjs。
  • 正例/负例:packages/skill-family-harness-node/test/foundation-015-harness.test.mjs。
  • 调用方仍拥有的业务语义:命令选择、正式启动、wrapper/argv 语义、签名与认证信任、宿主支持/生命周期资格、领域接受及重观察时机。

固定集合发布 (foundation.harness.fixed-set-publication)

createFixedSetPublicationManifest / publishFixedSet

  • 签名:createFixedSetPublicationManifest({ sourceRoot, targetParent, targetSegment });publishFixedSet({ sourceRoot, targetParent, targetSegment, manifest })(均为 async)。稳定入口也由 skill-family-harness-node/fixed-set-publication 导出。
  • 输入:同一规范父目录下的源目录、目标父目录、一个安全目标段和此前冻结的完整集合 manifest。
  • 输出:完整集合 manifest 与结构化 publication receipt。receipt 终态为 succeeded、refused、failed 或 indeterminate。
  • 语义边界:发布使用 Darwin renameatx_np(RENAME_EXCL) 或 Linux renameat2(RENAME_NOREPLACE) 的固定原生闭包;不使用检查后 rename 的 JavaScript 替代,不提供身份保护删除,不自动重试、回滚或恢复 indeterminate。
  • 副作用:仅在成功时对目标目录执行一次不替换发布;失败关闭。
  • since / stability:0.9.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/fixed-set-publication.mjs 与固定原生加载器。
  • 正例/负例测试:packages/skill-family-harness-node/test/stable-filesystem-operations.test.mjs 与既有固定集合边界测试。

replaceFixedSetAtomic

  • 签名:replaceFixedSetAtomic({ sourceRoot, targetParent, targetSegment })(async)。包根与 skill-family-harness-node/fixed-set-publication 子路径均导出。
  • 输入:已经完整生成的真实 sourceRoot、规范 targetParent 和一个安全 targetSegment。源目录与既有目标必须是同一规范父目录下的兄弟目录;两棵树只允许真实目录与单链接普通文件。
  • 输出:确认成功时返回目标路径、保留旧目标的 displacedTargetPath,以及 publicationState=published、commitState=exchange-committed、verification=verified、durability=namespace-synced 和两棵树的闭包摘要。
  • 提交语义:复验父目录、源和目标身份后,在同一父目录句柄下只执行一次 Darwin RENAME_SWAP 或 Linux RENAME_EXCHANGE。成功后,新集合完整位于目标路径,被置换的旧目标完整留在原 sourceRoot;Foundation 不删除任一目录。
  • 失败语义:受支持的提交前失败保持原目标路径和字节不变。机制失败抛 SFC2004 + details.kind=atomic-replace-failed;details 同时给出 phase、publicationState、commitState、verification 与 durability。不支持的平台使用 details.kind=unsupported-platform。
  • 重试边界:该操作不是幂等操作。相同参数再次调用会交换回原状态;确认成功后,或收到提交后及不确定错误时,不得盲目重试。Foundation 不自动执行第二次交换、回滚或清理。
  • since / stability:0.18.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/fixed-set-publication.mjs、稳定原生加载器与固定预构建闭包。
  • 正例/负例测试:packages/skill-family-harness-node/test/stable-filesystem-operations.test.mjs;Engineering Kit 离线投影由 packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs 覆盖。
  • 调用方仍拥有的业务语义:暂存目录的生命周期、成功后的旧目标清理,以及提交后或不确定失败的取证与恢复决定。

原子写 (foundation.harness.atomic-write)

writeFileAtomic

  • 签名:writeFileAtomic(root, relPath, data, { mode = 0o644 } = {})(async)
  • 输入:已收容目标路径、文件内容(string 或 Buffer)。
  • 输出:写入完成的文件,字节与输入一致。
  • 纯函数:否(落盘)。
  • 副作用:在根目录内创建临时文件,先 fsync 再 rename 覆盖目标;失败时回滚临时文件、不留残影。
  • 稳定错误码与 details.kind:越界路径抛 SFC2004 + PATH_TRAVERSAL/越界类 kind;非法数据类型 / 写失败 + ATOMIC_WRITE_FAILED。
  • 前置条件与信任锚:目标路径经 path-containment 验证在根目录内。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/atomic.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/atomic.test.mjs。
  • 调用方仍拥有的业务语义:写入内容的业务正确性。

临时工作区 (foundation.harness.temporary-workspace)

TemporaryWorkspace / createTemporaryWorkspace / withTemporaryWorkspace

  • 签名:
  • class TemporaryWorkspace(构造 (options))
  • createTemporaryWorkspace(options)(async)
  • withTemporaryWorkspace(fn, options)(async,回调式生命周期)
  • 输入:可选前缀/标签。
  • 输出:临时工作目录句柄;with 在回调结束后清理。
  • 纯函数:否(创建并删除系统临时目录子目录)。
  • 副作用:在宿主临时目录创建子目录,退出/异常时删除;不持久化。
  • 稳定错误码与 details.kind:创建失败 + WORKSPACE_CREATE_FAILED;清理失败 + WORKSPACE_DISPOSE_FAILED;已释放后使用 + WORKSPACE_DISPOSED。
  • 前置条件与信任锚:宿主提供可写临时目录(如 os.tmpdir);路径不逃逸出宿主临时根。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/workspace.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/workspace.test.mjs。
  • 调用方仍拥有的业务语义:临时产物的最终去处(持久态转 state-store)。

资源闭包 (foundation.harness.resource-closure)

computeResourceClosure / digestBytes / closureContains

  • 签名:
  • computeResourceClosure({ root, resources } = {})(async)
  • digestBytes(bytes)
  • closureContains(closure, relPath)
  • 输入:资源列表(路径 + 内容)。
  • 输出:确定性闭包对象与 sha256 摘要;closureContains 判定某相对路径是否在闭包内。
  • 纯函数:digestBytes / closureContains 是;computeResourceClosure 含按 root 读取资源,属受控只读。
  • 副作用:按 root 只读读取资源;不写。
  • 稳定错误码与 details.kind:非法/重复资源声明抛 SFC2004 + CLOSURE_CONFLICT / MISSING_RESOURCE。
  • 前置条件与信任锚:资源为可序列化文本条目(二进制投影明确 unsupported);去重与排序固定。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/closure.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/closure.test.mjs。
  • 调用方仍拥有的业务语义:资源业务含义。

进程监督 (foundation.harness.supervise-process)

superviseProcess / validateTimeoutPolicy

  • 签名:superviseProcess(options, deps = {})(async);validateTimeoutPolicy(policy)。
  • 输入:受约束的 command、args、cwd、环境、超时策略与既有监督选项。0.11.0 可选 rawSink 只接受 { root, stdoutFile, stderrFile, onClosed? }:根必须在打开时已是 fresh canonical 目录,两个文件名必须是不同的单段相对名。
  • 可选每流上限:outputByteLimits 为 { stdout?, stderr? },至少声明一流,各值为 0 到 Number.MAX_SAFE_INTEGER 的整数。按原始字节独立计数,等于上限允许,首次超过上限进入既有进程组终止流程。
  • 输出:一个既有的 watchdog-termination-envelope。rawSink.onClosed 只接收冻结的 stdout/stderr { sha256, bytes } 摘要; 它不创建第二种公开 envelope 或 receipt。
  • 副作用:启动一个受监督子进程。raw sink 在 spawn 前以 exclusive/no-follow、0600 打开两个文件,直到 child close、两个 stream close、全部排队写入、fsync 和 handle close 都完成才结束;exit 后到达的字节仍计入摘要。
  • 限额结果:仅配置上限时,evidence 增加 outputByteLimits 和 outputLimitExceeded;超限采用 output_limit_exceeded 终止原因。保存的截断流摘要只覆盖已保存字节。流、进程或写入终态未知时仍优先失败关闭。未配置上限保留旧行为。
  • 身份边界:调用方必须在整个调用期间独占 raw sink 的命名空间。文件句柄保护不会证明调用期间 pathname 或根目录身份始终不变; 前后检查只用于尽早失败。
  • 失败语义:选项形状错误抛 TypeError;机制失败抛 SFC2004,沿既有 supervise-process-failed 错误域失败关闭。rawStreamSink 仍是明确拒绝的名称;兼容别名、绝对路径、多段文件名、相同 stdout/stderr 名称与非 fresh 根均被拒绝。
  • 接线边界:不要因为单一消费者想在写正式证据前脱敏,就新增 rawStreamSink、transform sink、通用 sanitizer、第二个进程 runner 或新的公开 stdout 字段/回调。现有 rawSink 适合调用方接受在 fresh canonical 临时根中以 0600 保存原始 stdout/stderr 文件的场景;Foundation 不承诺 zero-plaintext-on-filesystem,也不拥有领域脱敏、跨流秘密发现或事后遮盖。
  • 若消费者有硬性零明文落盘要求,应由消费者基于明确威胁模型拥有该方案并暂停相关路径。至少出现第二个独立消费者和清晰共同合同前, 不重开 Foundation 的公共能力。
  • since / stability:监督入口自 0.5.0 / stable;受约束 raw sink 自 0.11.0,仅提供机制,不承诺宿主资格、认证、领域 判断或发布状态。
  • 源文件:packages/skill-family-harness-node/src/supervise-process.mjs。正反例测试: packages/skill-family-harness-node/test/supervise-process-validation.test.mjs、 packages/skill-family-harness-node/test/supervise-process-evidence.test.mjs。
  • 调用方仍拥有的业务语义:可执行程序选择、超时策略值、输出解释、认证、重试和发布决定。

请求管线 (foundation.harness.request-processing)

parseRequest / processRequest

  • 签名:
  • parseRequest(raw)
  • processRequest(raw, { now = () => new Date() } = {})(async)
  • 输入:原始请求负载(应符合 kernel 协议结构)。
  • 输出:规范化 operation-request 与终态 operation-result(终态集合固定为 REJECTED / FAILED / SUCCESS)。
  • 纯函数:parseRequest 是;processRequest 为纯函数管线(无外部副作用,默认 now 可注入以保证确定性测试)。
  • 副作用:无文件/Git/网络。
  • 稳定错误码与 details.kind:解析失败进入 REJECTED/FAILED 终态并带 SFC2002 / SFC2003 / SFC2004;机制失败 + EXECUTION_FAILED kind。
  • 前置条件与信任锚:请求符合 kernel 协议结构;业务语义由消费者拥有。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/request.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/request.test.mjs。
  • 调用方仍拥有的业务语义:操作的具体业务语义(状态机/重试转 loop-agent)。

报告 (foundation.harness.report)

validateReportModel / renderReportMarkdown / computeResultDigest / computeModelDigest / digestReport / buildBinding / verifyBinding / checkReport / collectStyleWarnings

  • 签名(节选):
  • validateReportModel(reportModel, { resultDocument } = {})
  • renderReportMarkdown(model)
  • computeResultDigest(resultDocument) / computeModelDigest(reportModel) / digestReport(reportMarkdown)
  • buildBinding(reportModel, resultDocument, reportMarkdown)
  • verifyBinding(binding, { reportModel, resultDocument, reportMarkdown } = {})
  • checkReport({ reportMarkdown, reportModel, resultDocument, binding } = {})
  • collectStyleWarnings(reportMarkdown)
  • 输入:report-model、渲染选项(locale / audience / style);SUPPORTED_REPORT_LOCALES = [zh-CN, en-US]。
  • 输出:Markdown 文本、绑定对象、分级检查发现;人类报告由机器结果派生,禁止自由撰写。
  • 纯函数:是(无时钟、无环境、无网络、无模型调用)。
  • 副作用:无文件/Git/网络。
  • 稳定错误码与 details.kind:SFC3001(REPORT_DIGEST_MISMATCH,绑定摘要不符或报告非模型规范渲染)、SFC3002(REPORT_ELEMENT_MISSING,强制元素缺失)、SFC3003(REPORT_FACT_DRIFT,报告改写绑定结果事实或字节与确定性再渲染不一致)。风格告警由 collectStyleWarnings 产出,仅建议、不编码、不阻断。
  • 前置条件与信任锚:REPORT_RENDERER_NAME / VERSION 取自各自 package(当前 0.3.0);双输出成组写入并拒绝路径别名与输入覆盖。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/report.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/report.test.mjs。
  • 调用方仍拥有的业务语义:报告业务结论的解读(编排由 Kit report 子动作负责)。

宿主适配机制 (foundation.harness.host-adapter)

normalizeAdapterSource / buildAdapterClosure / verifyAdapterBuildManifest / verifyPeerAdapterDirectories / materializeAdapterBuild / probeVersionVector

  • 签名:
  • normalizeAdapterSource(input)
  • buildAdapterClosure({ hostId, pathCategory, input } = {})
  • verifyAdapterBuildManifest(manifestInput, { hostId, pathCategory } = {})
  • verifyPeerAdapterDirectories({ request, peerRoots } = {})(async):从两个或更多真实 peer 根目录重算共同闭包、标准 manifest 和完整 logicalMappings。
  • materializeAdapterBuild({ targetRoot, build, writer = writeFileAtomic } = {})(async)
  • probeVersionVector({ hostId, capabilities, executable, argv, allowSpawn = false, timeoutMs = 5000, runner = spawnSync } = {})(async)
  • 输入:adapter source、目标路径、probe 选项。
  • 输出:构建闭包、校验后的清单、materialize 产物、版本向量。
  • 纯函数:normalizeAdapterSource / buildAdapterClosure / verifyAdapterBuildManifest 是;materializeAdapterBuild / probeVersionVector 含落盘或进程调用。
  • 副作用:materializeAdapterBuild 在受收容目标创建 sibling staging 并单次 rename;probeVersionVector 默认 allowSpawn=false,不取 PATH、不自动执行宿主二进制。
  • 稳定错误码与 details.kind:清单摘要不符 + MANIFEST_MISMATCH;目标已存在 + PORTABLE_PATH_COLLISION;非受信可执行文件 + UNTRUSTED_EXECUTABLE;构建/探测失败 + HOST_BUILD_FAILED / HOST_PROBE_FAILED;契约不符 + HOST_CONTRACT_INVALID;以上均包于 SFC2004。
  • 前置条件与信任锚:adapter source 为已声明文本闭包(content 类型固定 string,仅 utf8;二进制投影 unsupported);受信可执行文件方可 materialize。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/host.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/host.test.mjs。
  • 调用方仍拥有的业务语义:宿主具体业务语义与本地生命周期决策;Kit 只复用本节的绑定读取、严格不替换发布和原子写机制,不由 Harness 注册宿主别名或 driver。

verifyPeerAdapterDirectories 是只读入口。它逐级枚举和读取真实目录,拒绝符号链接、路径逃逸、非普通文件、缺失/多出或逐字节摘要不一致;mapping 必须唯一覆盖每个真实 SKILL.md。它按 peerId 归一化比较闭包,因此请求顺序不会影响结果。失败使用既有 SFC2003/SFC2004 与 details.kind,不返回部分成功,也不写入 peer 根目录。


持久状态底座 (foundation.harness.state-store)

openStateStore / appendEvent / readEvents / readSnapshot / writeSnapshot / verifyStateStore / rebuildSnapshot / inspectStateStoreLock / recoverStateStoreLock / closeStateStore / close

  • 签名(节选):
  • openStateStore(root, { owner, payloadSchemas, clock } = {})(async)
  • appendEvent(store, event)(async)
  • readEvents(store, { afterSequence = 0 } = {})(async)
  • readSnapshot(store, { reducer, initial = null } = {})(async)
  • writeSnapshot(store, state, { hostSessionRef, reducer, initial = null } = {})(async)
  • verifyStateStore(store, { reducer, initial = null } = {})(async)
  • rebuildSnapshot(store, reducer, { initial = null } = {})(async)
  • inspectStateStoreLock(root, { clock, recoveryObservation = false } = {})(async)
  • recoverStateStoreLock(root, options = {})(async)
    • 两种互斥接管模式,只能取其一:旧模式 { expectedOwner, expectedFencing, confirmOwnerTerminated: true, payloadSchemas };维护模式 { observation, confirmAllParticipantsStopped: true, confirmExclusiveMaintenance: true, payloadSchemas }。两种模式都必填 payloadSchemas(与 openStateStore 相同的注册表,至少一个 eventType/版本对),newOwner 与 clock 可选。
  • closeStateStore(store) / close(store)(async)
  • 输入:事件负载、快照、锁令牌。
  • 输出:事件、hash chain 校验结果、快照;STATE_GENESIS_DIGEST 作为链起点。
  • 纯函数:否(读写事件日志与快照文件,写协作式单写者锁)。
  • 副作用:在受收容路径读写事件日志与快照;写锁文件用于本地协作式单写者。
  • 稳定错误码与 details.kind:hash chain 断裂 + CHAIN_BROKEN;锁 fencing 冲突 + STORE_LOCKED;锁损坏 + LOCK_CORRUPT;恢复拒绝 + LOCK_RECOVERY_REFUSED;非法事件 + UNSAFE_STATE_ENTRY / EVENT_SCHEMA_INVALID;重复序号 + DUPLICATE_SEQUENCE;幂等冲突 + IDEMPOTENCY_CONFLICT;快照不一致 + SNAPSHOT_MISMATCH;已关闭 + STORE_CLOSED;以上均包于 SFC2004。
  • 恢复接管模式(互斥,不得混用):旧模式 recoverStateStoreLock(root, { expectedOwner, expectedFencing, confirmOwnerTerminated: true, payloadSchemas }) 要求 owner 与 fencing 精确匹配当前观测值;维护模式 recoverStateStoreLock(root, { observation, confirmAllParticipantsStopped: true, confirmExclusiveMaintenance: true, payloadSchemas, newOwner?, clock? }) 用完整观察覆盖 writer 缺失与部分写入的控制文件,不只核对 owner/fencing。显式写出但值为 undefined 的旧模式字段同样计入混用并被拒绝(legacy and maintenance recovery options cannot be mixed),构造维护模式 options 时必须整体省略旧模式字段。
  • 完整观察获取:对同一 root 调用 inspectStateStoreLock(root, { recoveryObservation: true }) 返回 state-store-recovery-observation 对象(闭字段 schemaVersion、kind、root、directories、controls;只读,不整理残留、不创建目录)。默认调用(不传该选项)返回的是诊断结果,不是有效观察,不能用于维护模式。维护模式的组织范围限于已验证的事件临时别名与 writer.lock、writer-mutation.lock、writer-recovery.lock 三种可处置控制残留;未知格式的控制记录或 fencing 计数器拒绝接管,未知文件不删除。
  • 前置条件与信任锚:事件日志为唯一权威,snapshot 为派生缓存;fencing 不承诺抵御同权限恶意进程;confirmOwnerTerminated 信任锚由调用方提供。维护模式的两项确认同样是外部信任前提,不是布尔字段自动实现的锁:confirmAllParticipantsStopped 声明旧写者、旧恢复者及其子进程均已停止,confirmExclusiveMaintenance 声明排他维护区间仍成立;区间从取得观察之前开始,到本次调用取得新写者句柄或失败返回结束,期间禁止其他恢复、正常打开、状态存储写入与相关业务写入。PID、年龄或 owner/fencing 比较都不能替代该前提。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/state-store.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/state-store.test.mjs。
  • 调用方仍拥有的业务语义:事件业务含义、reducer 转移、owner-terminated 信任锚(业务状态机/终态转 loop-agent)。

机制错误 (foundation.harness.errors)

HarnessError / mechanismError / HARNESS_ERROR_KINDS

  • 签名:
  • class HarnessError extends ContractsError(构造 (code, message, details),未登记码立即抛 TypeError)
  • mechanismError(kind, message, extraDetails)(返回 SFC2004 + 稳定 details.kind)
  • HARNESS_ERROR_KINDS(冻结对象)
  • 输入:错误 kind、上下文。
  • 输出:带稳定 kind 的错误对象;非法 kind 抛 TypeError。
  • 纯函数:是。
  • 副作用:无。
  • 稳定错误码与 details.kind:本模块不发明新码——机制失败统一 SFC2004(EXECUTION_FAILED),其注册含义为「机制运行时执行合规操作时失败;details 携带机制证据」;details.kind 取下列冻结枚举之一。
  • 前置条件与信任锚:HARNESS_ERROR_KINDS 冻结,新增 SFC 码属 Contracts 变更(不在本包写集)。
  • since / stability:0.2.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/errors.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/boundary.test.mjs、boundaries.test.mjs。
  • 调用方仍拥有的业务语义:错误业务归因。

HARNESS_ERROR_KINDS 冻结枚举(v1):

kind 含义
invalid-path / absolute-path / windows-drive-path / windows-path / unc-path 路径形态非法
path-traversal / symlink-escape / realpath-escape 收容逃逸
invalid-root 根目录非法
atomic-write-failed / read-failed 文件读写失败
missing-resource 资源缺失
workspace-create-failed / workspace-dispose-failed / workspace-disposed 临时工作区异常
closure-conflict / unsupported-policy 闭包/策略冲突
execution-failed / invalid-result 执行/结果异常
store-closed / store-locked / lock-corrupt / lock-recovery-refused 状态锁异常
unsafe-state-entry / event-schema-invalid / duplicate-sequence / idempotency-conflict / chain-broken / snapshot-mismatch 状态事件异常
host-contract-invalid / host-build-failed / host-probe-failed / untrusted-executable / portable-path-collision / manifest-mismatch 宿主适配异常
baseline-mismatch / content-guard-rejected 基线物化失败关闭
read-chokepoint-rejected 只读准入拒绝
surface-scan-violation / scan-policy-invalid 表面扫描失败关闭
upper-bound-exceeded 上限守卫越限

基线物化 (foundation.harness.baseline-materialization)

FND-ADR-009。把冻结基线物化为字节保真的临时副本:物化前校验源摘要、物化后同时校验副本摘要与源摘要(捕获物化中途的任一侧变化);副本内符号链接一律拒绝。

computeDirectoryDigest / materializeBaseline

  • 签名:
  • computeDirectoryDigest(rootDir)(async,返回 64 位小写 sha256 十六进制摘要)
  • materializeBaseline({ baselineDir, baselineDigest, prefix = "sf-baseline-" } = {})(async,返回物化根路径)
  • 输入:基线目录与冻结摘要。
  • 输出:确定性目录摘要;物化后的临时目录根路径。
  • 纯函数:否(读源树、在系统临时目录创建副本)。
  • 副作用:只读源基线;写系统临时目录并在失败时清理。
  • 稳定错误码与 details.kind:摘要不符(物化前或物化后)抛 SFC2004 + baseline-mismatch(details 含 phase:pre-materialization / post-materialization);目录不可用抛 invalid-root;建目录失败抛 workspace-create-failed。
  • 前置条件与信任锚:调用方持有冻结摘要;同一权限级进程可在物化窗口内改动源,机制以双端摘要捕获并失败关闭,不承诺抵御同权限恶意进程。
  • since / stability:0.3.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/baseline.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/baseline.test.mjs。
  • 调用方仍拥有的业务语义:残留内容判定(contentGuard 谓词)与副本最终去处。

TemporaryWorkspace.fromBaseline({ baselineDir, baselineDigest, prefix, contentGuard }) 与 createTemporaryWorkspace({ baseline: { ... } }) 把物化接入工作区生命周期:contentGuard 缺省为允许(字节保真是机制契约,残留判定归消费者);守卫抛错包装为 content-guard-rejected 并 dispose 副本。


只读 chokepoint (foundation.harness.read-chokepoint)

FND-ADR-009。把受保护区域的读取集中到一个准入入口:允许根集合 + 可选身份谓词;越界、链接逃逸与非授权身份一律 read-chokepoint-rejected。

createReadChokepoint

  • 签名:createReadChokepoint({ allowRoots, allowIdentity } = {}) → { assertReadAllowed, read }
  • 输入:非空允许根集合;可选身份谓词 (identity) => boolean。
  • 输出:准入后的 { root, relPath, absolute } 或受收容读取结果。
  • 纯函数:否(async,含只读文件系统访问)。
  • 副作用:只读 realpath / 收容读取;不写。
  • 稳定错误码与 details.kind:越界/逃逸/非授权抛 SFC2004 + read-chokepoint-rejected;资源缺失抛 missing-resource;参数非法抛 TypeError。
  • 前置条件与信任锚:调用方声明允许根集合与身份规则;机制不解释任何私有身份或路径语义。
  • since / stability:0.3.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/chokepoint.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/chokepoint.test.mjs。
  • 调用方仍拥有的业务语义:允许根集合、身份谓词、准入后读取语义。

字符串输入与 { root, relPath } 输入走同一 resolveContained 收容分类(含 macOS /var → /private/var 等符号链接前缀根的统一规范化)。


策略化表面扫描 (foundation.harness.surface-scan)

FND-ADR-009。按 surface-scan-policy 契约文档对声明表面做路径与内容模式扫描:首个命中即失败关闭;策略非法或模式不可编译同样失败关闭;缺失扫描文件不静默跳过。

scanSurface

  • 签名:scanSurface({ root, relPaths, policy, encoding = "utf8" } = {})(async)
  • 输入:扫描根、相对路径清单、策略契约文档。
  • 输出:{ scanned, bytes, policy }(冻结对象)。
  • 纯函数:否(只读文件系统访问;进程内正则编译,无持久状态)。
  • 副作用:只读;不写。
  • 稳定错误码与 details.kind:命中抛 SFC2004 + surface-scan-violation(details 含 kindOfHit:path / content);策略非法或模式不可编译抛 scan-policy-invalid;缺失文件抛 missing-resource;参数非法抛 TypeError。
  • 前置条件与信任锚:策略文档通过契约校验;allowedUses 只携带不解释,命中不被豁免(豁免由消费者层实现)。
  • since / stability:0.3.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/surface-scan.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/surface-scan.test.mjs。
  • 调用方仍拥有的业务语义:策略内容、允许用途语义与命中后的处置。

注入式自测约定:扫描器无状态——注入模式并扫描后移除注入,再次扫描结果字节一致(自测见测试文件,不冒充独立复核)。


token 上界估算 (foundation.harness.token-estimation)

FND-ADR-009。确定性领域估算原语,两个互相独立的估算器:UTF-8 字节数上界(estimateTokenUpperBound)与按 CJK 码位/空白切分的词元数估算(estimateTokens,算法 cjk-char-whitespace-split)。两者均为无模型、无网络、无 tokenizer 依赖、无持久状态导入的纯函数;字节上界结果符合 token-estimate-result 契约(无时间戳,guarantees 为封闭枚举)。每条词元估算记录携带估算器 id 与版本(SFA-CONTEXT-028:消费方必须能回答结果出自哪个估算器),两个估算器的结果不得静默混用、不得互相替代。

estimateTokenUpperBound

  • 签名:estimateTokenUpperBound(text)(纯函数)
  • 输入:文本字符串。
  • 输出:token-estimate-result 对象(upperBound === inputBytes)。
  • 纯函数:是;零依赖。
  • 副作用:无。
  • 稳定错误码与 details.kind:非字符串输入抛 TypeError(无 SFC 码)。
  • 前置条件与信任锚:输入为 JavaScript 字符串;估算只承诺上界(字节数即上界),不承诺真实 token 计数。
  • since / stability:0.3.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/token-estimate.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/token-estimate.test.mjs。
  • 调用方仍拥有的业务语义:估算结果的解释与消费侧换算(模型调用与真实 token 计数不在 Foundation)。

estimateTokens / isCjkCodePoint / 估算器常量

  • 签名:
  • estimateTokens(text)(纯函数)
  • isCjkCodePoint(codePoint)(纯函数)
  • 常量:TOKEN_ESTIMATOR_ID(skill-family.token-estimator)、TOKEN_ESTIMATOR_VERSION(1.0.0)、TOKEN_ESTIMATION_ALGORITHM(cjk-char-whitespace-split)、CJK_CODE_POINT_RANGES(冻结码位区间表)
  • 输入:文本字符串;isCjkCodePoint 接收整数码位。
  • 输出:冻结的词元估算记录(kind: skill-family.token-estimate-record,schemaVersion: 1),携带 estimator.id / estimator.version / algorithm、输入统计(codePoints / inputBytes)、切分统计(cjkCharacters / whitespaceSeparators / otherRuns)与 tokens;unit 为 tokens,precision 为 deterministic-heuristic,scope 为 content-text-only。
  • 算法(cjk-char-whitespace-split,逐码位单遍扫描):
  • CJK 码位区间(冻结):U+3400–U+4DBF(扩展 A)、U+4E00–U+9FFF(统一表意文字)、U+F900–U+FAFF(兼容表意文字)、U+20000–U+3134F(扩展 B–G)。
  • 每个 CJK 码位计 1 词元,并立即终结其前尚未闭合的 OTHER 段。
  • 连续的非 CJK、非空白码位构成 OTHER 段,被空白或 CJK 码位分隔时每段计 1 词元。
  • 空白(ECMAScript \s 类)只起分隔作用,不贡献词元。
  • 恒等式:tokens === cjkCharacters + otherRuns;中英混排、纯 CJK、纯 ASCII、空串(0 词元)全部适用。
  • 纯函数:是;零依赖、零 import(模块纯度由测试复检)。
  • 副作用:无。
  • 稳定错误码与 details.kind:非字符串输入抛 TypeError(无 SFC 码)。
  • 前置条件与信任锚:估算是对目标 tokenizer 的确定性启发式近似,不承诺与任何具体模型 tokenizer 相等;比较阈值时同一批次必须使用同一估算器(记录内的 estimator 与 algorithm 即裁决依据)。
  • since / stability:0.6.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/token-estimate.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/token-estimator.test.mjs(中英混排、纯 CJK、纯 ASCII、空串与空白串、扩展 B 码位、区间边界、记录封闭键集、恒等式、确定性、CLI 子进程行为)。
  • 调用方仍拥有的业务语义:阈值策略与超限处置;把启发式词元数换算为目标模型的真实消耗。

CLI:skill-family-token-estimate

  • 入口:harness 包 bin skill-family-token-estimate(src/token-estimate-cli.mjs);与工程 Kit 的四命令互不混用。
  • 用法:skill-family-token-estimate (--text <s> | --file <p> | --stdin) [--estimator tokens|upper-bound|both];默认 --estimator tokens。both 输出 { tokens, upperBound } 两个键,明示两个估算器并存而非混合。
  • 输出:stdout 打印 JSON 估算记录(tokens 为估算记录,upper-bound 为 token-estimate-result),换行结尾。
  • 副作用:只读取命令行参数、--file 指定文件或 stdin;只写 stdout。
  • 稳定退出码:0 成功;2 用法错误(输入源缺失或互斥、未知参数、--file 目标不是普通文件等,stderr 给出原因);--help 打印用法后退出 0。
  • 前置条件与信任锚:--file 按调用方给定的路径原样读取,CLI 不做路径收容;需要收容时在库内用 readFileContained。
  • since / stability:0.6.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/token-estimate-cli.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/token-estimator.test.mjs(子进程 CLI 用例:确定性、--file/--stdin/both、用法错误退出码 2、--help)。
  • 调用方仍拥有的业务语义:输入文本的采集与裁剪策略、输出记录的归档位置。

通用上限守卫 (foundation.harness.upper-bound-guard)

FND-ADR-009。复用 state-store 事件账与 token-lock 显式占用实现通用上限守卫:越限事件失败关闭且不写入;上限值、单位类别与超限策略全部由消费者配置,模块不携带任何固定数额或定价词汇。

openUsageGuard / appendUsageEvent / readUsage / closeUsageGuard

  • 签名:
  • openUsageGuard({ stateRoot, owner, payloadSchemas, reducer, initial = 0, upperBound, lockRoot, lockPath, clock } = {})(async)
  • appendUsageEvent(guard, event, { beforeCommit } = {})(async)
  • readUsage(guard)(async)
  • closeUsageGuard(guard)(async)
  • 输入:事件负载、纯归约函数、非负上限、状态根与锁根/锁路径。
  • 输出:追加结果、当前用量读数、守卫句柄。
  • 纯函数:否(写事件账与锁文件)。
  • 副作用:在受收容路径写事件账与锁文件;打开时显式占用锁、关闭时释放。
  • 稳定错误码与 details.kind:越限抛 SFC2004 + upper-bound-exceeded(details 含 upperBound / projected,事件不写入);锁被占用抛 store-locked;事件账断链抛 chain-broken;事件 schema 违规抛 event-schema-invalid。
  • 前置条件与信任锚:lockRoot/lockPath 由消费者指定在 state store 根之外;事件账是唯一权威;fencing 不承诺抵御同权限恶意进程。
  • since / stability:0.3.0 / stable。
  • 源文件:packages/skill-family-harness-node/src/budget-guard.mjs。
  • 正例/负例测试:packages/skill-family-harness-node/test/budget-guard.test.mjs。
  • 调用方仍拥有的业务语义:事件含义、归约函数、上限数值与超限后的业务处置(定价与计费语义留在消费者)。

Quickstart Profile v2 candidate

规范入口 skill-family-harness-node/quickstart-profile 负责创建 observation Resource、Task 与终态 Result,并复验真实 文件字节、Resource id 全局唯一性、Task digest、operation 身份、逐字段 run/stage/attempt 以及 evidence 精确回指。 历史入口 skill-family-harness-node/candidate/quickstart-profile 在弃用窗口内解析同一模块;消费者应迁移一次。 verifyQuickstartExchange 把机制拒绝转换成结构化结果,抛出式入口继续使用已登记的 SFC2004 与稳定 details.kind。

invokeFoundationMechanism

invokeFoundationMechanism(request) 是固定机制桥接。调用方只能选择预先登记的 operation,不能传入模块名、导出名或任意函数。0.8.2 新增的 read-file-strict 直接调用上文的 readFileStrict:

{
  "operation": "read-file-strict",
  "params": {
    "root": "/absolute/consumer-root",
    "path": "authority/frozen.json",
    "encoding": "utf8",
    "expectedSha256": "<lowercase-sha256>"
  }
}

params 是闭合对象。root 与 path 是必填非空字符串;encoding 只能是 utf8 或省略;expectedSha256 省略时不做预期摘要比对,提供时沿用核心严格读取合同。

桥接保留核心回执的 path、sha256、bytes 与 mode。UTF-8 内容仍是字符串;二进制内容投影成 Node 标准的 Buffer JSON 形态 { "type": "Buffer", "data": [...] },以便通过 JSON 传输后无损还原字节。

直接调用失败时沿用核心异常,包括 SFC2004 与 details.kind。候选 mechanisms-cli.mjs 继续使用一请求一响应 JSON:成功退出 0,拒绝或用法错误退出 2;CLI 错误 JSON 只承诺 name 与 message,不承诺跨语言保留 details。

该入口不选择 method,不解释 domainResult,也不拥有重试、调度或生命周期。消费者必须把 Contracts、Harness 与 Engineering Kit 精确锁定到同一版本;不能从 Foundation 工作树导入源码。0.3.0 的 v2 与 0.2.1 的 v1 不兼容。 迁移到规范入口和 Schema 身份后,后续仅晋升 stable 不再要求改合同身份;消费者仍需更新精确 pin 才能取得新发布的 stable 承诺,Bundle 是否重建由既有包字节与 provenance 绑定输入决定。

rename-directory-no-replace 的规范入口是 skill-family-harness-node/rename-directory-no-replace;历史 /candidate/rename-directory-no-replace 入口解析同一原生原语。 该原语仍不等同于稳定的高层 fixed-set-publication,消费者应根据所需合同选择,不得用别名混淆两个能力层次。


机制批量 (foundation.harness.mechanism-batch)

FND-DES-022。有界、同操作、顺序的跨进程批量传输:把一组相互独立的 canonical-json 请求合并为一次进程启动与传输,逐项结果与错误字节等价于同版本原单请求调用。已经位于同一 Node 进程内的调用不强制改批。本切片只实现该批量合同,不新增常驻服务、并发、缓存、重试、跨项引用、工作流、收据或注册表。

runMechanismCliBatch / mechanisms-cli.mjs --batch

  • 签名:
  • runMechanismCliBatch({ input = stdin, output = stdout, error = stderr, invoke } = {})(async,返回整体退出码)
  • CLI 显式模式:node <同版本官方 Bundle 内的 mechanisms-cli.mjs> --batch,从标准输入读取恰好一个 JSON 文档,写出一个批次响应后退出。带 --batch 且出现额外参数时在读取输入前拒绝;无 --batch 时仍运行旧 runMechanismCli 单请求入口,不对旧请求新增容量限制。
  • 输入:恰好含 operation(固定 canonical-json)与 inputs(非空有序数组,每项恰好 { "document": <任意 JSON 值> })的一个 JSON 文档。不支持 NDJSON、会话协议、数组自动探测、每项自带操作或嵌套批次。顶层缺/多字段、项缺 document、空数组与未知操作属于整批结构失败。
  • 输出:{ "results": [{ "inputIndex", "exitCode", "response" }] },长度与输入一致、序号从 0 连续递增;exitCode 只取 0(成功)或 2(失败)。成功项 response 为原机制结果;失败项为原 CLI 的 { ok: false, error: { name, message, code?, details? } } 错误对象。逐项还原规则固定为 JSON.stringify(response) + "\n",退出码 0 对应原 stdout、2 对应原 stderr,另一通道为空;错误对象不重新排序或规范化。
  • 纯函数:是(逐项经既有固定分派器 invokeFoundationMechanism 执行,不引入第二套算法;测试可注入既有可信 invoke,但输入 JSON 不得指定函数、模块、路径或覆盖分派器)。
  • 副作用:无文件/网络/进程副作用,无残余状态;只写调用方提供的 output/error 流(默认进程标准流)。
  • 容量(固定政策,权威值由 Contracts mechanism-batch-policy.json 持有,本页与 Harness 从该权威派生,调用方不可调高):
限制 含边界的最大值 计量对象与检查时点
输入项数 256 解析后、逐项调用前
请求字节 16 MiB(16,777,216) 原始 UTF-8 流含空白,拼接与解析前累计
响应字节 32 MiB(33,554,432) 完整 JSON 响应与最后换行,发送前累计确认
  • 失败语义:请求字节、输入项数或结构的预检拒绝在任何机制调用前发生,stdout 为空,error 流写一个批次错误对象并整体退出 2。输出容量只能在当前项已经返回后确认;超限时停止后续项,stdout 仍为空,error 流写批次错误对象并退出 2。错误为 TypeError 投影,details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit,不新增 SFC 错误码。畸形 UTF-8、畸形 JSON 与输入流错误属传输失败,保留原异常投影,不伪装为机制业务失败、不伪造某个 inputIndex。单项机制失败(含 unsafe integer 等留给原分派器按项判断的约束)经原 CLI 错误投影写入该项 response 并继续执行后续项。输出通道失败时可能已有部分字节送出;整体退出 2,消费者必须把截断 JSON、通道错误或进程无正常完成结果判为传输失败,不能从前缀认定批次成功。若连错误通道也写入失败,错误对象可能无法交付。
  • 整体退出码三分支:所有机制项成功 → 0,stdout 为完整批次结果加一个换行、stderr 空;至少一个机制项失败 → 2,stdout 仍为完整批次结果、stderr 空;批次预检、输出容量或传输失败 → 2。预检与输出容量失败时 stdout 空、stderr 为一个批次错误对象与换行;输出通道失败时不承诺收回已经发送的字节。
  • 前置条件与信任锚:Contracts、Harness 与 Engineering Kit 精确锁定同一版本;程序化函数与 CLI 都经调用方已安装并验证来源的官方 Bundle 消费(Bundle 由同版本三包生成,保留来源身份、摘要与完整性检查),不从 Foundation 工作树导入源码;调用方提供 input/output/error 流。已有 Schema 批量校验(validate-many-by-schema-id)继续使用原入口,不嵌套、不重新包装。
  • since / stability:0.19.0 / candidate。candidate 不等于 stable,本地候选测试通过也不改变成熟度;是否发布须查对应版本的发布后验证证据,不能从 stability 推断。
  • 源文件:Contracts 新 Schema packages/skill-family-contracts/candidate/foundation-mechanisms/mechanism-batch-request.schema.json、mechanism-batch-result.schema.json 与容量权威 mechanism-batch-policy.json;Harness packages/skill-family-harness-node/candidate/mechanisms-cli.mjs;Kit 离线 Bundle 投影 packages/skill-family-engineering-kit/candidate/profile-bundle.mjs。
  • 正例/负例测试:packages/skill-family-contracts/test/quickstart-profile.test.mjs、packages/skill-family-harness-node/test/quickstart-profile.test.mjs、packages/skill-family-engineering-kit/test/candidate-mechanisms-cli.test.mjs、packages/skill-family-engineering-kit/test/candidate-profile-bundle.test.mjs。
  • 调用方仍拥有的业务语义:领域分组与容量切分、请求间依赖关系判断、精确 pin 与来源身份绑定、批次采用完成与领域回归判定。逐项迁移示例:把若干 { "operation": "canonical-json", "params": { "document": ... } } 单请求合并为 { "operation": "canonical-json", "inputs": [{ "document": ... }, ...] },再按 results[i].inputIndex 读回逐项 response 与 exitCode;同一 Node 进程内的直接调用继续使用 invokeFoundationMechanism,不被强制改成批量。

多路径文件集合应用与恢复 (foundation.harness.file-set-recovery)

applyFileSet / recoverFileSet / pruneFileSetRecovery

  • 签名:
  • applyFileSet(request, { validate, beforeMutation, afterMutation })(async;validate 必填,缺省不得自动通过)
  • recoverFileSet(request)(async)
  • pruneFileSetRecovery(request)(async)
  • 输入:Contracts 登记的 file-set-apply-request、file-set-recovery-request 与 file-set-prune-request。请求携带 operationId、规范绝对真实 root 与已批准的 rootBinding、固定 recoveryRelPath(.foundation-file-apply)、allowAdjacentStaging、environment(filesystem 为 apfs 或 ext4,cooperativeWriters 为 true)与 validationTimeoutMs;apply 另有最多 1024 条有序操作(path/action/expected/next)。bytes 只存在于 JS 调用参数,不进入机器 JSON;原字节与新字节合计上限 256 MiB。恢复必须另有 maintenance 观察(observation 加两项确认);该观察由调用方在排他维护区间内对根内固定 .foundation-file-apply/journal 调用 inspectStateStoreLock(journalRoot, { recoveryObservation: true }) 取得,observation.root 必须等于该 journal 目录,默认诊断结果不是有效观察、不能用于故障接管;prune 请求只接受同一根绑定与 environment,在无残留时直接取得正常 writer,只有需要故障接管时才要求显式提供同一 maintenance。
  • 输出:file-set-result。outcome 取 committed、commit-unconfirmed、rejected、rolled-back、recovery-required、already-committed、already-rolled-back、pruned 或 already-pruned;paths 按原请求顺序逐项给出 apply、restore、current 与 errorKinds,分别表达历史意图、恢复动作与最近一次安全观察,不合成单一布尔值;materials 给出材料相对路径、none|retained|partial|pruned、durable 与 adjacentStaging: none-observed|possible-unknown。
  • 恢复材料布局:根内固定 .foundation-file-apply/ 下使用 journal/(既有 state-store 事件账)与 operations/<id>/{before,after}/<index>。材料默认保留,只有显式 pruneFileSetRecovery 清理精确的已终结操作,journal 保留;机制不按后缀删除归属不明的邻接暂存文件,只报告 possible-unknown。
  • 副作用:业务路径上的写入复用既有严格单文件原语(publishFileOrReplace / replaceFileAtomic),恢复材料写在根内受收容路径。不发起网络、不启动子进程、不写 Git、不修改进程 umask。
  • 失败语义:可捕获的机制失败返回 file-set-result,不只抛一个错误。外码沿用 SFC2004,details 携带闭枚举 kind 与 phase(input/preflight/prepare/apply/validate/restore/finalize/prune),消息仅供人阅读、不能用于分支。整组前检失败、环境不支持与容量越限在任何业务写入前返回;领域验证返回 false、抛错、超时、非法结果或迟到完成触发自动恢复且不提交,验证状态与恢复状态分开报告;恢复遇冲突路径保留外部内容并继续其他安全项;全局独占或根身份问题停止整组;有效提交事件决定不回滚,目标复核或持久化未确认时报告 commit-unconfirmed 并保留材料。释放锁失败不改写已确认终态,只追加 lock-release-failed。
  • 保证边界:未为该路径写入持久 apply-intent 事实前不触碰任何业务路径。不承诺瞬时多文件可见性,也不承诺抵御不合作或同权限恶意并发写者——写者交错只由调用方的合作式独占前提阻止。恢复要求调用方先停止旧参与者与旧恢复者、在外部建立排他维护区间并提交该区间的完整观察与确认;清理在无残留时直接取得正常 writer,只有需要故障接管时才要求同一维护前提。机制不自动偷锁、不竞争恢复、不猜测损坏材料。
  • since / stability:0.21.0 / candidate。candidate 不等于 stable,本地候选测试通过也不改变成熟度;是否发布须查对应版本的发布后验证证据。消费者在评估期必须精确锁定三个 Foundation 包。
  • 源文件:packages/skill-family-harness-node/src/file-set-recovery.mjs(根导出见 src/index.mjs);Contracts 侧 file-set-apply-request、file-set-recovery-request、file-set-prune-request、file-set-result、file-set-event-payload 与 state-store-recovery-observation。
  • 正例/负例测试:packages/skill-family-harness-node/test/file-set-recovery.test.mjs、packages/skill-family-harness-node/test/file-set-recovery-crash.test.mjs、packages/skill-family-contracts/test/file-set-contract.test.mjs。
  • 调用方仍拥有的业务语义:业务计划与原/新字节的冻结、validate 的领域判断与异常详情、维护区间的建立与旧参与者停止确认、恢复材料的最终去处、精确 pin、采用资格与领域验收判定。

与机器事实层的互链

  • 能力稳定 ID 见 docs/agents/capability-catalog.json(foundation.harness.*)。
  • 机械校验:scripts/docs/capability-catalog-check.mjs 解析 src/index.mjs,拒绝引用不存在的入口。

消费方契约测试替身(fake) (Foundation 0.14.0)

createAtomicWriteFake({ vector }) 是按能力具名导出的官方测试替身,入口为 skill-family-harness-node/contract-testing。它要求传入已由 Contracts 校验、身份与 精确版本匹配且尚未消费的 atomic-write 向量;调用签名保持 writeFileAtomic(root, relPath, data, options),但测试替身不访问真实文件系统。

fake.identity 固定暴露 capabilityId、vectorSetId 与 foundationVersion。 fake.observation() 返回冻结的调用参数摘要和 return、throw 或 indeterminate 结果。测试替身覆盖向量声明的成功、拒绝与不确定路径,不判定消费者领域保证;消费者须 另行运行至少一条受控真实公共调用路径。

Windows 原生支持与边界

Foundation 0.28.0 的 Windows 原生分支适用于 Node.js ≥22.22.2 且 <23、Windows 11 x64、本地 NTFS 路径与普通用户权限环境。该版本的 API 成熟度依据登记状态判断,新增世代 API 保持 candidate 状态;精确版本的远端发布可用性需通过正式发布凭据核实,不能替代真实宿主业务验证。

原生装载采用包内五平台 manifest、软件物料清单(SBOM)与收据构成的封闭预构建集合,消费者无需编译器,装载时不下载二进制文件,亦无 JavaScript 安全回退机制。POSIX 既有合同保持不变。

路径与文件系统语义

  • 路径使用大写盘符与正斜杠表示,如 C:/work/project。
  • 输入路径分隔符可归一化为正斜杠,目录名大小写按真实目录处理,不进行全路径转小写。
  • 支持长路径、空格及中文文件名,内部使用 UTF-16 编码,但不公开内部扩展前缀。
  • 拒绝以下路径形式:
  • UNC 路径(如 \\server\share)
  • 设备路径(如 \\.\C:)
  • 盘符相对路径(如 C:work)
  • 指向 ADS(Alternate Data Streams)的路径
  • 尾随点或空格的路径组件
  • 保留设备名(如 CON, PRN, AUX 等)
  • 包含 junction 或 reparse point 的路径组件
  • 仅当 symlinkPolicy.mode=record 时,可记录符号链接自身原始信息(UTF-16 target 与 reparseTag),不跟随目标路径。

原生身份与权限模型

createFilesystemRootBinding 保持 kind、digestAlgorithm、basis、digest 四字段,Windows 的 basis 为 canonical-finalpath-volume-fileid-type-security-v1,不新增版本字段。observeFilesystemTree 的 Windows 观察使用 schemaVersion=2。

Windows 权限观测是闭对象 {kind, attributes, securityDigest}:kind 固定为 windows-security-v1,attributes 为原生文件属性的无符号 32 位整数,securityDigest 为 64 位小写十六进制。摘要覆盖 owner、group、DACL 及相关控制标志,不读取需要特权的 SACL;它用于核对观测一致性,不穷尽有效访问权限。readFileBound 的 rootMode 也为 null,rootPermissionObservation 使用同一结构。

  • 原生身份由 volumeSerial/fileId、安全描述符摘要与文件属性共同构成。
  • 不可从 POSIX mode 伪造 Windows 权限,权限信息由 Windows 安全描述符直接提供。
  • readFileBound 的 mode 与 statMode 字段返回 null,权限信息通过 permissionObservation 字段记录。
  • 所有读取、遍历与严格发布操作均需通过原生句柄验证身份。
  • 普通文件仅支持单链接;硬链接被拒绝。
  • 严格发布时,permissions.kind 仅支持:
  • windows-inherited:新文件继承父目录权限
  • windows-preserve:保留原始目标文件的权限设置
  • 公共 mode 在 Windows 平台被拒绝,私密机制使用当前用户 owner,DACL 仅允许当前用户与 SYSTEM,首字节前已设好,普通消费者无法将 windows-protected 当作公共策略使用。
  • 恢复操作会尝试还原原 owner、group、DACL、READONLY/HIDDEN/SYSTEM/ARCHIVE 四个属性,并在整组前进行实际测试以验证还原能力。
  • 不会主动申请权限提升,恢复过程依赖当前用户权限。

readFileStrict 保留对根路径 "." 的便利支持,其行为在 Windows 上先进行词法规范化,不用 realpath(root) 洗白重解析路径;规范化后的绝对路径需经原生安全核验,确保根、祖先及最终文件均在许可范围内,盘符相对路径(如 C:foo)、UNC 路径及设备命名空间路径均被拒绝。该接口不放宽对 readFileBound 或 createFilesystemRootBinding 所要求的严格根绑定准入,既有错误分类继续传播:摘要错误、缺失、读取错误、被拒绝的链接及路径越界均按原分类传播,不回退至普通读取。 POSIX 原行为不变。

可执行入口与明确的 Node 解释器

explicitNode 分支要求 lookup.mode=absolute-path。脚本同样须为普通单链接文件;脚本与 Node 各自必须只匹配一个绑定根,两者可以位于不同根中。允许的脚本类型包括:

  • 后缀为 .js、.mjs 或 .cjs 的文件,可无 shebang;
  • 无扩展名的文件,但首行必须精确匹配以下任一声明:
  • #!/usr/bin/env node
  • #!node
  • #!node.exe

shebang 必须从同一原生句柄读取并验证的字节中判断,且仅接受完整声明,不带附加参数。无扩展名脚本不接受缺失 shebang;其他后缀的文件继续拒绝。不将未知脚本类型猜测为 Node 脚本。仅 .js、.mjs、.cjs 后缀的文件允许无 shebang,无扩展名脚本则必须有上述三种 shebang 之一。

脚本字节、摘要与权限的当次观测结果作为后续复核的基准。输出版本 v2 的 canonicalEntry.entryKind=interpreter-script,interpreter.request 为 Node 的规范路径,interpreter.canonicalEntry 为同次观测的 Node 身份,shebangArgs=[],launch.file 为 Node 路径,argvPrefix 仅包含脚本的规范路径。脚本与 Node 在返回前及启动前均需复核绑定关系与摘要一致性。

当未传入 explicitNode 时,仅观察 PE 原生入口。explicit-path-search 按调用者提供的 pathEntries 顺序执行:在 pathEntries 的每个根目录内,先匹配调用者提供的完整命令名,无扩展名时再尝试 command.exe,已有扩展名则不再追加。存在候选但非合格 PE 文件时明确拒绝,不跳转至环境 PATHEXT、当前目录或其他解释器。absolute-path 仅查询指定路径。上述通用查找入口拒绝 .cmd 和 .bat 文件。工程对已知 npm/pnpm shim,从已核实的对应安装包解析实际 npm-cli.js/pnpm.cjs 等 Node 入口,并构造上述 explicitNode 输入。用户可在 cmd/PowerShell 中运行 npm 生成的 CLI shim,内部不使用 shell:true 或拼接命令字符串。

固定世代发布与整批固定读取

Windows 明确不支持旧的 replaceFixedSetAtomic 双目录交换,不能以普通重命名替代。POSIX 的原交换合同保留。以下两个新增入口同时从包根与 skill-family-harness-node/fixed-set-publication 导出。

  • 新增两个核心 API 用于固定世代管理:
  • publishFixedSetGeneration({storeRoot, sourceRoot, generation, expectedCurrent})
  • resolveFixedSetGeneration({storeRoot})

发布世代(publishFixedSetGeneration)

  • sourceRoot 必须是 storeRoot 内以 generation 命名的真实子目录。
  • generation 为安全单段名,不能为 current。
  • 世代必须先完整生成,之后保持不可变。
  • expectedCurrent 为前置条件,表示当前指针状态,首次调用为 null。
  • 该操作要求单写者协作;expectedCurrent 是点时前置条件,不提供并发 CAS 保证。
  • 指针内容包含:
  • schemaVersion=1
  • kind=skill-family.fixed-set-generation-pointer
  • generation
  • closureDigest

解析世代(resolveFixedSetGeneration)

  • 安全读取指针并验证整个世代闭包。
  • 返回:
  • pointer:指针对象
  • generationRoot:世代根目录的路径
  • rootBinding:根绑定信息

  • 调用者每个读取批次仅需调用一次 resolveFixedSetGeneration,并将同一 generationRoot 与 rootBinding 传给所有 readFileBound 调用。

  • 不能对每个文件重新读取 current 指针。
  • 旧世代不会自动删除,静默期与清理由消费者自行决定。
  • 发布结果返回字段:
  • status:发布状态
  • commitState:提交状态
  • verification:闭包验证结果
  • durability:刷新请求及确认状态
  • indeterminate 表示提交结果尚未确定,不能按提交前失败盲目重试。

文件集合恢复与 Job Object 清理

文件集合恢复使用 v2 协议,请求中声明 environment.filesystem=ntfs;POSIX 系统仍沿用 v1 及 apfs/ext4 合同。恢复过程需排他维护,所有旧参与者须被终止。恢复材料默认保留,不自动清理。flush-requested 仅表示已请求刷新文件与目录内容,不提供断电事务保证。

文件集合的逻辑准入规则在整组前检时执行:路径必须是 UTF-8 文本,并符合 NFC 规范化,同一请求中若存在大小写或 Unicode 归一化别名,则整组请求被拒绝,且不产生任何业务写入。此限制仅作用于逻辑命名层面,不因 NTFS 实际支持大小写敏感而放宽。即使在真实 NTFS 目录中可共存 A 与 a,该同组 apply 仍按逻辑合同拒绝。此行为非 NTFS 本身冲突,而是为保障可移植性与命名一致性所设的前置校验。

安全访问、文件树遍历与固定集合扫描仍遵循真实 NTFS 目录的大小写规则,即实际路径匹配以文件系统语义为准,不依赖逻辑命名规则。

以下四个 async 接口仅用于 Windows/NTFS;其他平台在修改前拒绝。root 与原先批准的 rootBinding 必须对应同一根,身份变化时拒绝,不能重新捕获绑定来批准替代根。目录记录中的身份与 permissionObservation 来自同一创建或打开句柄。

inspectFileSetRecovery —— 恢复状态只读探查

inspectFileSetRecovery({ root, rootBinding, recoveryRelPath: ".foundation-file-apply", environment })
  • async: true
  • 合法环境:仅接受 {filesystem: "ntfs"} 或 {filesystem: "ntfs", cooperativeWriters: true},未知字段或其他值均拒绝。声明不能代替实际 NTFS 与运行时检查。
  • 调用前提与副作用:只读,不要求合作写者确认、独占访问或预先取得维护观察,不创建或修改文件系统对象。

返回状态(result.status)

状态 语义说明
absent 机制根目录实际缺失
admitted 合格私密空根,或已验证完成且无参与者、未终结操作、未知或损坏材料的历史记录
refused 本次只读核验拒绝,保留原失败原因

错误结构(result.error)

  • null:当状态为 absent 或 admitted 时
  • 否则:{ code, message, details: { kind, phase, path? } }
  • code: SFC2004
  • details.kind: 既有 file-set 错误种类
  • details.phase: input 或 preflight
  • details.path: 仅限有效业务成员路径,绝不包含机制路径

语义约束

  • 机制根缺失即 absent:若实际路径不存在,返回 absent,不尝试重建
  • 准入范围:合格空根可以尚无 journal/operations;未终结操作、参与者、未知或损坏材料均拒绝。
  • prune 记录可能解释缺失:若存在已记录的 prune 操作,可解释材料缺失;但无证明即拒绝
  • 历史状态不等同当前业务字节:当前业务数据无需与旧终端状态一致;缺失/陈旧头/缓存为推导结果,非权威性损坏
  • 末次复核要求:
  • 返回前必须重新检查原始参与者状态、事件边界、所有已检查目录身份及完整成员集合
  • 任何读取错误、变更检测、不确定性均拒绝返回,不自动重试
  • 事件链未变也不能放过新增未知材料
  • 非保证项:
  • 不保证原子快照
  • 不保证独占访问证明
  • 不保证返回后稳定性
  • 不保证未来变更授权
  • 操作身份:不创建或消费 operationId。

prepareFileSetParents —— 准备文件集合父目录

prepareFileSetParents({ root, rootBinding, paths })
  • async: true
  • 输入 paths:
  • 仅限授权业务相对路径
  • 自动推导所需父目录,去重,按浅层优先顺序处理
  • 遵循原始文件集路径/容量契约
  • 权限继承:
  • 新建业务目录继承实际父目录权限
  • 已存在 ACL 不变
  • 安全性验证:
  • 原始根及祖先的原生句柄身份已验证
  • 拒绝重解析(reparse)或被替换的祖先路径
  • 必要句柄保持持有
  • EEXIST 行为:
  • 必须先安全复核为既存真实目录,才记入 existing;不纳入本次创建记录
  • 返回结构: text { status: "succeeded" | "failed" | "indeterminate", created: Array<{ path, volumeSerial, fileId, permissionObservation }>, existing: Array<{ path, volumeSerial, fileId, permissionObservation }>, unconfirmed: Array<string>, // 仅相对路径字符串,非伪造身份 error: null | { kind, message } // 原始 HARNESS_ERROR_KINDS }
  • 部分成功:
  • 创建成功但刷新失败,仍保留创建状态
  • 不保证目录链原子性

createPrivateMaterialDirectory —— 创建私有材料目录

createPrivateMaterialDirectory(root, relPath, { rootBinding })
  • async: true
  • 输入 relPath:
  • 仅允许一个直接子目录路径,禁止递归
  • 私有安全策略:
  • 所有者为当前用户
  • DACL 为受保护的非继承型,仅允许当前用户与 SYSTEM
  • 创建时设置,不支持任意 ACL 或模式选项
  • 已存在处理:
  • 仅接受已存在的有效私有真实目录
  • 绝不收紧已有宽泛 ACL
  • 返回 existing 而非强制抛出 EEXIST
  • 返回结构:
  • 与 prepareFileSetParents 相同闭合结构
  • created / existing / unconfirmed 三组互斥
  • 总数最多一个有效条目

removePreparedFileSetParents —— 移除已准备的父目录

removePreparedFileSetParents({ root, rootBinding, directories })
  • async: true
  • 输入 directories:
  • 仅接受来自同次 prepareFileSetParents 返回的 created 条目
  • 绝不接受 existing 条目
  • 操作效果:
  • 按深度逆序删除
  • 验证原始根、祖先和记录目录的同一身份
  • 仅在持有保护的前提下删除空目录
  • 无递归,无任意清理
  • 返回结构: text { status: "succeeded" | "failed" | "indeterminate", entries: Array<{ path, status: "removed" | "already-absent" | "retained" | "indeterminate", error: null | { kind, message } }>, error: null | { kind, message } }
  • 状态语义:
  • removed:已知删除,即使父目录刷新失败,仍保持删除状态
  • already-absent:当前即不存在,非组恢复或权限覆盖替换
  • retained:未安全删除,因权限、替换、外部内容或全局停止;不证明存在或未变
  • indeterminate:删除状态未知,绝不作为普通 retained 报告
  • 全局不安全:
  • 若全局根或祖先不再可信,立即停止不安全的后续删除
  • 所有未尝试项均保留,并附带原因

目录操作结果聚合规则

优先级 状态 说明
1 indeterminate 任意一个条目为 indeterminate,整体结果为 indeterminate
2 failed 没有不确定项,但有错误或未完成要求
3 succeeded 所有条目完成,无错误或未确认项
  • 错误处理:
  • 错误优先级:首个不确定原因 → 首个错误
  • 成功时 error 为 null
  • 类型错误:
  • 仅在任何变更前允许 TypeError
  • 变更后返回结构化已知/未知部分事实,不抛异常

applyFileSet 的可选回调

applyFileSet(request, { validate, beforeMutation, afterMutation })
  • 可选参数:
  • beforeMutation
  • afterMutation
  • 上下文:冻结对象 { index, path, action }
  • 执行顺序:
  • 串行 await 执行
  • beforeMutation 在最终原生根/父/目标重检前执行
  • afterMutation 仅在实际变更 + 后验证 + 事件应用成功后执行
  • 拒绝行为:
  • 任一回调抛错或拒绝均发生在 commit 前,进入原自动恢复,并保留 apply-failed / apply 的因果消息
  • 调用边界:回调不在 recover / prune 中调用,不重放,也不自动重试。
  • 超时:
  • validate 的超时期限不覆盖可信回调
  • 可信回调须自行负责结束

runProjection 整个调用仍要求调用方确认 cooperativeWriters: true 并提供合作式独占访问;真正的 apply、recover、prune 操作保留原确认要求。只读核验结果不授权后续修改。以上说明 Windows 分支的调用边界;API 成熟度与精确版本发布状态需分别核对。

superviseProcess 与 Job Object

superviseProcess 使用 schemaVersion=2。挂起创建后,先关联 kill-on-close Job Object,再恢复主线程。stdin/stdout/stderr 句柄被封闭继承,防止泄漏。环境变量 env={} 可用,按 Node/libuv Windows 规则补全系统运行必需变量;显式提供的环境变量(含空字符串)优先于默认值。不保证完全无环境,但提供最小运行时上下文。

超时、预算、输出上限与残余后代均通过 TerminateJobObject 清理。成功提交强杀请求后,forcedKill=true。windowsJob 字段包含五项布尔观测状态:

  • associatedBeforeResume:Job Object 是否在恢复前已关联
  • terminationRequested:终止请求是否已发出
  • activeProcessZeroObserved:是否观察到活动进程为零
  • handleClosed:Job Object 句柄是否已关闭(仅指 Job Object 句柄,不涵盖进程或线程句柄)
  • cleanupCompleted:清理完成状态

cleanupCompleted 的达成需满足以下全部条件:

  • 活动进程数为零
  • 双流收尾、私密原始流刷盘并关闭
  • 所有句柄(含 Job、进程、线程)已关闭
  • 整个过程受 killGraceSeconds 限制,即从 TerminateJobObject 发出后开始计时,用于等待 Job 归零与输出收尾

Windows 结果不包含 processGroupId 字段;POSIX 分支保留原进程组标识逻辑。原始流从私密创建、写入、刷新到关闭,全程使用同一原生句柄,确保一致性。