版本兼容定义¶
审计消费 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 兼容,当且仅当同时满足:
contractsVersion与 pin 相同;auditSurfaceVersion与 pin 相同;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-r2provenance 与独立重签叙事,该声称与本仓事实不符,已就地修正 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-planstable Schema,加入有限manual支持、maturity/sourceAliases与 digest 绑定的本地生命周期计划语义;同时新增业务中立的adapter-peer-verification-request与adapter-peer-verification-resultR05 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三个候选顶层契约,并将 KimidriverVersion=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 仍按既有机制变化) |
消费方响应动作:
- pin 升级:消费方把 foundation-pin(或等价钉扎)升级到含该行为变更的版本;禁止在旧 pin 上假设新行为。
- adoption-lock 重生成:受影响消费方重新生成 adoption-lock(或等价声明载体),使
declared_foundation_surface与foundation_versions反映新 pin 字节。 - 先建后删:行为变更以 Foundation 侧行为测试(含 bundle 字节对象测试)落地为先,消费方删除自身重验测试在后(D2 顺序)。
行为归属记录(2026-08-19):「宿主运行时(node)不可用 → 无回退、fail-closed」的触发面(node 解析/env 检查)属于消费方调用边界(SFA 侧为 D3 已裁决接受的残余风险,仅保留调用点声明检查);Foundation 侧等价语义 = 写入环节失败时 fail-closed(无部分产物、错误码正确、无本地回退),由 atomic 行为测试承接,不在 Foundation 建宿主 spawn 测试。