跳转至

版本兼容定义

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

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

三者都由 describeAuditSurface() 一次性给出，审计侧把它们与当前 Contracts 版本对应的基线 pin 比对（当前为 baseline/contracts-1.12.0.pin.json）。

兼容规则

一个被消费的 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 不改写。
  • 审计运行时先做包锁验证（见 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 测试。