跳转至

版本兼容定义

审计消费 Contracts 以两个版本坐标 + 一个摘要为准:

坐标 来源 含义
contractsVersion Contracts 源码候选版本(当前 1.21.0) 机器契约内容的版本
auditSurfaceVersion 审计消费接口自身的版本(当前 1) 消费面形状的版本
surfaceDigest digestAuditSurface()(SHA-256) 消费面的精确字节指纹

describeAuditSurface() 仅返回当前被导入的 Contracts 包所对应的审计表面,其中包含 contractsVersion、auditSurfaceVersion 及摘要输入。在执行校验时,审计侧依据实际消费包的 surface.contractsVersion 动态选择对应的基准文件,即 baseline/contracts-<version>.pin.json,并据此核对版本与摘要。当实际消费 Contracts 1.21.0 时,使用 baseline/contracts-1.21.0.pin.json 作为核验基准;若实际消费 1.20.0、1.19.0、1.18.0 或 1.17.0 等历史版本,则分别使用对应版本的 contracts-1.20.0.pin.json、contracts-1.19.0.pin.json、contracts-1.18.0.pin.json、contracts-1.17.0.pin.json 等只读基准文件进行兼容性校验。所有历史版本的 pin 文件均保持只读状态,新增 1.21.0 的 pin 不会导致旧版本基准失效或被覆盖。

兼容规则

一个被消费的 Contracts 包与某个基线 pin 兼容,当且仅当同时满足:

  1. contractsVersion 与 pin 相同;
  2. auditSurfaceVersion 与 pin 相同;
  3. digestAuditSurface() 与 pin 的 surfaceDigest 相同。

由于 surface 摘要覆盖了登记表、错误码、规则、kernel 协议、全部 schema 文档与引擎参数,摘要相同蕴含内容逐字节等价(规范化意义下)。三个条件任一不满足即不兼容:审计必须报告 AUD-BASE-001(运行期基线检查)或 AUD-LOCK-001(包锁验证),并拒绝给出通过裁决。

变更分级

变更 分级 需要的动作
不改变 surface 字节的变更(如注释、测试) 无影响 无需新 pin
改变 surface 字节但不改变含义的变更 不兼容 禁止以"同义"为由免检;必须走合同变更并重新批准 pin
新增审计消费接口(只读、增量) auditSurfaceVersion 递增 新 pin + 本文件更新
改变既有消费接口含义 auditSurfaceVersion 递增 + 合同变更 新 pin;旧 pin 存档不删
Contracts 版本演进(1.0.0 → 下一版本) contractsVersion 变化 新的基线 pin 文件;旧 pin 文件只读存档

pin 生命周期

  • 每个经版本化批准的 Contracts 发布对应一个 pin 文件:baseline/contracts-<version>.pin.json;
  • pin 是 append-only:批准后不再原地编辑,作废以新 pin 取代并在 note 中说明;
  • pin 由产品侧在冻结时刻构造(provenance product-compatibility-fixture):摘要来自对已冻结产物的 digestAuditSurface() 机械计算,事实清单直接对照合同文档推导,不取自生成器或 oracle;本仓库不存在独立的第二审阅会话,pin 不作任何独立角色声称;
  • 诚实性修正(2026-08-05):旧 pin(1.0.0、1.1.0)曾携带 independent-r2 provenance 与独立重签叙事,该声称与本仓事实不符,已就地修正 provenance 与 note;修正只触及 provenance/note 两处诚实性字段,不改变任何 digest 或 facts 字段,旧 pin 继续作为只读兼容存档;
  • Contracts 1.1.1(2026-08-05):仅描述补丁(migration-manifest schema 三处 description 改写为稳定产品语义;无任何校验关键字、公开 API、错误码、规则或引擎参数变化)。按本生命周期新增 contracts-1.1.1.pin.json 为现行基线,contracts-1.1.0.pin.json 转为只读兼容存档。1.1.1 pin 相对 1.1.0 pin 的准确事实:校验语义和事实清单不变(facts 逐项一致);四个 Contracts 文档(registry、error-codes、rules、kernel-protocol)因内嵌 contractsVersion 从 1.1.0 更新到 1.1.1 而改变摘要;migration-manifest Schema 因上述三处 description 更新而改变摘要;其余五个 Schema(project-manifest、profile-descriptor、managed-file-lock、operation-request、operation-result)摘要不变。proof-independence.mjs 的 P5 强制这套如实声明的 provenance 词汇(pin:product-compatibility-fixture;变异夹具:product-fixture);
  • Contracts 1.2.0(2026-08-09):报告能力线增量,不是描述补丁:新增 report-model、report-binding 两个顶层契约和 SFC3001~SFC3003 报告错误码,改变了公开机器合同与审计事实。
  • Contracts 1.3.0(2026-08-09):宿主接入能力线增量,不是描述补丁:新增 host-descriptor、host-capability-fact、adapter-build-manifest、host-operation-plan、host-operation-receipt 五个顶层契约,改变了公开机器合同与审计事实。
  • Contracts 1.4.0(2026-08-09):持久状态能力线增量,不是描述补丁:新增 state-event-envelope、state-snapshot-metadata 两个顶层契约,改变了公开机器合同与审计事实。
  • Contracts 1.5.0(2026-08-16):FND-ADR-010/011 能力线增量,不是描述补丁:新增 declared-read-surface-result、structured-scan-policy 两个顶层契约(顶层对象集合 20 → 22),改变了公开机器合同与审计事实。该 pin 的摘要与事实均从当前 describeAuditSurface()/digestAuditSurface() 机械投影,provenance 仍为 product-compatibility-fixture。
  • Contracts 1.6.0(2026-08-18):审计整改 C5 能力线增量,不是描述补丁:新增 public-boundary-declaration、platform-difference-registry、observation-scope、profile-adoption-declaration、audit-baseline-pin、token-estimate-record 六个顶层契约(顶层对象集合 24 → 30),改变了公开机器合同与审计事实;未新增 SFC 错误码,规则与 kernel 协议仅随 contractsVersion 字段更新。pin 合同本身(audit-baseline-pin)与消费面校验函数 verifyBaselinePin()(AUD-BASE-001 / AUD-LOCK-001 编码)在本版本落地(GAP-5 / SG-28)。
  • Contracts 1.7.0(2026-08-22):FND-ADR-013 的 Project Profile 能力线增量。新增 project-profile 顶层契约(顶层对象集合 30 → 31),统一 scaffold 项目根声明的机器结构;未新增 SFC 错误码。contracts-1.7.0.pin.json 由 scripts/baseline-pin-gen.mjs --update 从 describeAuditSurface()/describeBaselinePin() 机械生成,并经过合同校验和 verifyBaselinePin() 自校验;现作为历史只读兼容存档保留。
  • Contracts 1.8.0(2026-08-24):新增业务中立的 source-authority-receipt 顶层契约(31 → 32),以及纯校验、解析 API;未新增 SFC 错误码。contracts-1.8.0.pin.json 由 scripts/baseline-pin-gen.mjs --update 从公开 Contracts 表面机械生成并自校验;1.7.0 及更早 pin 保留为只读兼容存档。
  • Contracts 1.9.0(2026-08-24):新增业务中立的 filesystem-root-binding、fixed-set-publication-manifest 和 fixed-set-publication-receipt 三个顶层契约(32 → 35)。错误码、规则、检查类型、预算、Kernel 操作和校验策略均未变化。contracts-1.9.0.pin.json 由 scripts/baseline-pin-gen.mjs --update 从公开 Contracts 表面机械生成并自校验;1.8.0 及更早 pin 保留为只读兼容存档。
  • Contracts 1.10.0(2026-08-24):Foundation 0.10.0 扩展已登记的 host-descriptor、host-probe-result 和 host-operation-plan stable Schema,加入有限 manual 支持、maturity/sourceAliases 与 digest 绑定的本地生命周期计划语义;同时新增业务中立的 adapter-peer-verification-request 与 adapter-peer-verification-result R05 Schema,顶层对象由 35 类增至 37 类。未新增 SFC 错误码,registry、rules、error-codes 重新记录 1.10.0 坐标,Kernel 协议仍按既有生命周期保持 1.8.0 字节基线。contracts-1.10.0.pin.json 由 scripts/baseline-pin-gen.mjs --update 从公开 Contracts 表面机械生成并自校验;1.9.0 pin 保留为只读兼容存档。
  • Contracts 1.11.0(2026-08-25):Foundation 0.11.0 新增 host-verification-request 与 host-verification-result 业务中立 Schema,顶层对象由 37 类增至 39 类;Harness 增加原始字节 sink,Engineering Kit 提供 candidate 受约束真实宿主验证入口(Kimi 与 WorkBuddy 两个内置 driver,复用现有登录态)。contracts-1.11.0.pin.json 由 scripts/baseline-pin-gen.mjs --update 从公开 Contracts 表面机械生成并自校验;1.10.0 及更早 pin 保留为只读兼容存档。
  • Contracts 1.12.0(2026-08-26):扩展既有 host-descriptor 的固定宿主验证组合,并允许 host-verification-result 在退出码为零但输出协议不合法时表达执行失败。顶层对象仍为 39 类,无新增 Schema ID 或错误码。registry、rules、error-codes 更新版本坐标,Kernel 保持 1.8.0 字节基线。新 pin 只由 scripts/baseline-pin-gen.mjs --update 从公开表面生成并自校验;1.11.0 及更早 pin 不改写。
  • Contracts 1.13.0(2026-08-26):增加 plugin-verification-request、plugin-verification-result 和 filesystem-tree-observation 三个候选顶层契约,顶层对象由 39 类增至 42 类;同时为 watchdog 信封增加可选的每流输出限额事实,未启用限额的旧调用保持原形状。contracts-1.13.0.pin.json 由公开表面机械生成并保留为历史只读兼容存档。
  • Contracts 1.14.0(2026-08-28):增加消费者契约测试向量与能力采用字段,明确区分候选发现、迁移完成、契约接入完成和真实宿主资格;消费者向量仍是候选测试合同,不改变既有宿主验证身份。contracts-1.14.0.pin.json 保留为历史只读兼容存档。
  • Contracts 1.15.0(2026-08-29):增加 executable-identity-observation、skill-family-directory-verification-request 和 skill-family-directory-verification-result 三个候选顶层契约,并将 Kimi driverVersion=1.0.0 与闭合 cliVersion=0.39.1 分开。顶层对象由 42 类增至 45 类;Kernel 仍为 1.8.0,审计消费面仍为 auditSurfaceVersion=1。contracts-1.15.0.pin.json 的 supersedes 指向不可变的 contracts-1.14.0.pin.json;更早 pin 均继续作为只读兼容存档。
  • Contracts 1.16.0(2026-09-07):新增 engineering-baseline 顶层契约,顶层对象由 45 类增至 46 类;它只登记中立身份、规则谱系引用与 Foundation 参考骨架身份,不把 Audit 规则正文或发布状态复制进 Contracts。contracts-1.16.0.pin.json 保持历史只读。
  • Contracts 1.17.0(2026-09-07):为有界机制批量候选重记版本承载文档,稳定顶层对象仍为 46 类,批量合同保持 candidate-only,不进入稳定登记表。contracts-1.17.0.pin.json 是该历史时点最近已发布规格的只读基线。
  • Contracts 1.18.0(2026-09-10,未发布候选):扩展稳定 host-descriptor 的封闭验证组合,允许 cursor 与 cursor-agent-print-v1 的唯一配对;顶层对象、错误码、规则、Kernel 协议和 auditSurfaceVersion 不变。contracts-1.18.0.pin.json 从公开 Contracts 表面机械生成并指向不可变的 1.17.0 pin;Cursor CLI 的 / 菜单发现与显式调用已通过,Foundation npm 包版本仍由发布计划单独递增。
  • Contracts 1.19.0(2026-09-15,本地未发布候选):新增 professional-conclusion 顶层契约,其登记状态为 candidate,登记对象由 46 类增至 47 类。project-manifest 同期增加可选 engineering 声明, 用于登记发布单元的版本来源和工程入口。错误码、规则、Kernel 协议和 auditSurfaceVersion 不变。 contracts-1.19.0.pin.json 从当前公开 Contracts 表面机械生成并指向只读的 1.18.0 pin;该 pin 只记录 本地候选消费面,不代表独立审计结论或发布完成。
  • Contracts 1.20.0(2026-09-17,本地未发布候选):新增 file-set-apply-request、file-set-recovery-request、 file-set-prune-request、file-set-result、file-set-event-payload 和 state-store-recovery-observation 六个顶层契约,登记状态均为 candidate,登记对象由 47 类增至 53 类。错误码、规则、Kernel 协议和 auditSurfaceVersion 不变。contracts-1.20.0.pin.json 从当前公开 Contracts 表面机械生成并指向只读的 1.19.0 pin;该 pin 只记录本地候选消费面,不代表独立审计结论或发布完成。
  • Contracts 1.21.0(2026-10-24,0.28.0 发布准备记录):
    本轮 Foundation 0.28.0 发布准备采用 Contracts 1.21.0,登记对象由 53 个增至 56 个,新增三个 schemaVersion=1 的世代对象:fixed-set-generation-pointer、fixed-set-generation-result、fixed-set-generation-resolution,其登记状态均为 candidate。相关合同的 Windows v2 分支已扩展,POSIX v1 原有保证保持不变。三份版本承载文档 registry.json、rules.json 和 error-codes.json 的 contractsVersion 字段统一更新为 1.21.0,其规则正文、预算、错误码及含义均未变更。Kernel 文档 1.8.0 全部字节保持不变,auditSurfaceVersion 仍为 1。

本地 scripts/baseline-pin-gen.mjs --update 已机械追加 baseline/contracts-1.21.0.pin.json,其 supersedes=contracts-1.20.0.pin.json;所有历史 contracts-<version>.pin.json 文件均保持只读,未被修改或覆盖。官方 npm 包 skill-family-contracts@0.27.1 实际承载 Contracts 1.20.0 与 53 个对象,其四个文档和 53 个 Schema 的摘要与旧 contracts-1.20.0.pin.json 匹配;本轮目标包坐标为 0.28.0;截至这份 2026-10-24 发布准备记录,远端发布与正式核验尚待完成。该 contracts-1.21.0.pin.json 为产品兼容夹具,不构成独立审计或发布批准。

  • 审计运行时先做包锁验证(见 isolation-and-lockfile.md),再做变异重放;pin 不匹配时,变异重放结果不得被采信。

profile 行为变更纪律(2026-08-19,D6)

Foundation 对外暴露的 profile 机制面是消费方 pin 的行为契约,包括 FOUNDATION_MECHANISM_OPERATIONS 8 个 operations 与 runner.mjs 直接导出(含 publishFileExclusive 等函数的选项面)。profile 行为变更 = profile 版本变更:行为语义漂移不得在不升版本的前提下发生。stability 维持 candidate-only(D6)期间同样适用——candidate profile 的字节一致性由 pin digest 约束,行为语义变更必须走版本坐标,不因 candidate 状态而豁免。

变更 分级 需要的动作
8 个 operations 之一的分派语义变化(参数、结果、错误 kind) profile 行为变更 包版本递增(candidate 阶段为 candidate 版本递增)+ 本文件更新
runner 直接导出面变化(新增/删除/改变导出,含 publish 函数族) profile 行为变更 包版本递增 + 本文件更新
publish 选项面变化(2026-08-19 D5 为 publishFileExclusive 新增 createParents 选项即此类;选项是 Foundation 侧契约,消费面只传参) profile 行为变更 包版本递增 + 本文件更新
不改变行为的字节变更(注释、格式化) 无影响 无需版本动作(pin digest 仍按既有机制变化)

消费方响应动作:

  1. pin 升级:消费方把 foundation-pin(或等价钉扎)升级到含该行为变更的版本;禁止在旧 pin 上假设新行为。
  2. adoption-lock 重生成:受影响消费方重新生成 adoption-lock(或等价声明载体),使 declared_foundation_surface 与 foundation_versions 反映新 pin 字节。
  3. 先建后删:行为变更以 Foundation 侧行为测试(含 bundle 字节对象测试)落地为先,消费方删除自身重验测试在后(D2 顺序)。

行为归属记录(2026-08-19):「宿主运行时(node)不可用 → 无回退、fail-closed」的触发面(node 解析/env 检查)属于消费方调用边界(SFA 侧为 D3 已裁决接受的残余风险,仅保留调用点声明检查);Foundation 侧等价语义 = 写入环节失败时 fail-closed(无部分产物、错误码正确、无本地回退),由 atomic 行为测试承接,不在 Foundation 建宿主 spawn 测试。