feat(aw): add versioned contract validators - #3214
Merged
casparant merged 12 commits intoSep 11, 2026
Merged
Conversation
kongche-jbw
force-pushed
the
feat/aw/contracts-preview
branch
from
September 11, 2026 08:39
03b3416 to
e01b39c
Compare
- Preserve the v1 projection input and output reference shapes. - Keep reference resources separate from the active schema registry. Signed-off-by: Caspar Zhang <caspar@linux.alibaba.com> Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Preserve v1 content, code and command inspection reference shapes. - Keep findings typed without adding provider execution code. Signed-off-by: Caspar Zhang <caspar@linux.alibaba.com> Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Unify name, coverage and security outcome constraints. - Require recovery metadata and preserve media and input identity. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Share identity, evidence and coverage shapes across contract records. - Separate runtime observation from control grants and operation state. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Bind projection candidates and inspection results to their inputs. - Represent coverage and recovery explicitly in versioned payloads. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Describe provider negotiation, bounded calls and correlated receipts. - Distinguish returned candidates from observed adoption evidence. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Record ordered plan steps, settlement and final execution intent. - Keep OS protection evidence distinct from provider declarations. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Reject ambiguous JSON and define bounded canonical document encoding. - Keep raw byte identity separate and check Rust, Python and JS vectors. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Compile exact schema resources offline and expose pinned references. - Check each payload fixture and reject unknown fields and bad names. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Check invocation, receipt, adoption and lifecycle consistency. - Use shared fixtures and explicit negative cases for evidence failures. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Require ordered settlement and exact evidence at dispatch and adoption. - Keep scenario setup separate and use named invocation evidence fields. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
- Document the experimental library and reproducible local checks. - Link encoding, schema, record and plan tests from paired usage guides. Signed-off-by: kongche-jbw <kongche.jbw@alibaba-inc.com>
kongche-jbw
force-pushed
the
feat/aw/contracts-preview
branch
from
September 11, 2026 08:41
e01b39c to
e66449d
Compare
kongche-jbw
marked this pull request as ready for review
September 11, 2026 10:24
casparant
approved these changes
Sep 11, 2026
This was referenced Sep 12, 2026
2 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
本 PR 为 #3124 提供 AW 的合同基础层:版本化 JSON Schema,以及可在离线环境中校验这些记录的
aw-contractsRust 库。它检查输入输出形状和证据之间的一致性,不启动服务、不执行 Provider,也不接管 Agent 或授予执行权限。提交顺序沿着四层展开:保留 v1 参考 → 定义当前合同形状 → 实现编码、结构和语义校验 → 提供使用入口。这样可以先审阅协议表达了什么,再审阅代码如何检查这些约束。以下每一项对应一笔提交。
1.
d0762ee8d— 保留 projection 的 v1 Schema 参考加入 context projection 的输入、输出两份 v1 Schema,保留既有投影协议的数据形状,供审阅版本演进时对照。这一步只有 Schema 文件,没有引入 Core、Host 或实际文本替换逻辑;这些 v1 资源也不会注册到后面的当前校验器。
2.
03f692b5a— 保留 inspection 的 v1 Schema 参考加入 content、code、command 三类检查的输入和输出,共六份 v1 Schema。它与上一笔组成八份参考资源,表达检查请求及结构化结果,不包含具体安全引擎。这两笔主要来自 Caspar Zhang,均保留 Caspar 与 kongche-jbw 的两行
Signed-off-by。3.
a1c8d9eaa— 收紧 v1 参考合同的约束在前两笔的数据形状上统一名称、检查覆盖范围和安全结果的约束,并补足恢复信息、媒体类型及输入关联要求。它集中呈现同一组 Schema 的语义收紧,方便直接检查哪些原本可接受的数据现在会被拒绝;仍不注册或执行这些参考合同。
4.
8912dab13— 定义当前合同共享的身份与生命周期形状建立
common-v1,集中定义 scope、名称、摘要、证据和 coverage 等公共形状;随后定义 runtime binding、boundary descriptor、control grant 和 operation record。后续能力合同复用这些形状,从数据层区分“观察到了某个运行时”和“拥有控制该运行时的授权”,并记录状态操作的生命周期。5.
f47a36eb4— 定义 v2 能力输入输出基于公共形状,加入 projection 及 content/code/command inspection 的八份 v2 Schema。投影结果携带候选内容和恢复信息,检查结果表达覆盖范围及结构化发现。这里只回答能力请求和结果应当长什么样;它们是否对应某次真实调用,由后面的跨记录校验处理。
6.
0bbbc5658— 把能力结果放入可关联的调用记录加入 provider descriptor、capability invocation、provider receipt 和 context adoption 四类 Schema,表达 Provider 声明、Schema 版本与摘要、调用预算、返回记录及采用观测。它把上一笔的能力 payload 放入调用上下文,同时将“Provider 返回了候选结果”和“调用环境确认采用了结果”分开,避免仅凭返回值认定结果已生效。
7.
8a6eb4d6c— 定义计划执行与最终动作的证据加入 capability plan、plan execution、execution intent 和 OS protection binding 四类 Schema。计划描述需要执行哪些步骤,执行记录描述各步骤如何结束;执行意图与 OS 保护记录则供最终 dispatch 校验使用。至此,当前 Registry 所需的 21 个 Schema 资源已齐备,但还没有 Rust 校验实现。
8.
33bcabe38— 建立 Rust 库与确定的编码、摘要规则建立独立 Cargo workspace、依赖锁文件和
canonical模块。严格解析拒绝重复键、非允许数值、过深或过大的文档,并提供规范化 JSON 编码与摘要;原始字节摘要与规范化文档摘要保持不同含义。Rust 测试及 Python/JavaScript 向量检查随实现加入,为后面比较 Schema 和记录摘要提供一致基础。9.
fd46017c3— 注册 Schema 并校验单份记录的形状实现离线 Registry,编译前面定义的 21 个 Schema,提供按名称校验以及获取精确 Schema ID/摘要的接口。加入覆盖全部 20 种 payload 的合成 fixture、共享测试装载器和 Schema 测试,验证合法样例、未知字段及非法名称。通过这一层只说明单份记录符合形状,尚不能证明多份记录相互一致。
10.
a4ba99e72— 校验调用、结果、采用和生命周期的关联在 Registry 上增加跨记录校验:检查调用与 Provider/运行时/边界是否匹配,receipt 是否绑定同一输入并满足预算,以及采用记录是否具备有效文本、恢复信息和支持的证据。另校验控制授权、执行意图和状态操作转换。对应反例测试覆盖过期身份、错绑结果、虚假收益、检查覆盖不足和非法状态转换;相近案例用数据表表达,共享合成 fixture。
11.
239d7dbb4— 将单次校验组合为计划级证据检查基于上一笔的单次调用校验,检查计划步骤是否按序结算、所选 Provider 是否全部有记录、拒绝或取消是否被错误改成成功,以及最终 dispatch/adoption 是否绑定正确的计划与证据。这些函数校验调用方提供的记录,本身不执行计划或阻断操作。测试将 Scenario 构造放到独立辅助文件,使用具名的 invocation、receipt、output 字段,让测试正文集中表达拒绝、缺步、重放和过期保护等行为。
12.
e66449d24— 提供双语使用与审阅入口加入中英文 README,说明实验性接口边界、运行检查的方法,以及编码、Schema、记录和计划四类测试的位置。说明当前注册资源与 v1 参考文件的区别,并明确调用方仍负责证据认证和实际动作执行。
验证与后续边界
四个引入 Rust 能力的阶段(第 8–11 笔)分别通过以下检查,命令从
src/aw执行:cargo fmt --all -- --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo test --workspace --locked cargo doc --workspace --no-deps --locked python3 tests/check_canonical.py环境为 Linux ARM64,Rust 1.97.1、Python 3.12.3、Node.js 24.15.0。最终共 28 项 Rust 测试通过,跨语言摘要向量一致;测试覆盖离线合同校验,尚未验收实际 Agent 或 Provider 接入。生产 Rust、Schema、fixture 和依赖锁文件与整理前的合同版本一致,测试整理保留了原有测试及反例。
本 PR 保持 Draft,不关闭 #3124。根目录组件注册、模块 AGENTS 和 changelog 等模块基本接线完成后统一补齐;AW 专项 CI 留在后续独立阶段。当前 API 和 Schema 仍是实验接口,需要匹配精确版本与摘要,没有自动版本转换。移除新增
src/aw目录即可撤回此基础组件,无需迁移用户数据。