Skip to content

feat(aw): add versioned contract validators - #3214

Merged
casparant merged 12 commits into
agentic-os-org:mainfrom
kongche-jbw:feat/aw/contracts-preview
Sep 11, 2026
Merged

casparant merged 12 commits into
agentic-os-org:mainfrom
kongche-jbw:feat/aw/contracts-preview

Conversation

@kongche-jbw

@kongche-jbw kongche-jbw commented Sep 10, 2026 •

Copy link
Copy Markdown
Collaborator

本 PR 为 #3124 提供 AW 的合同基础层:版本化 JSON Schema,以及可在离线环境中校验这些记录的 aw-contracts Rust 库。它检查输入输出形状和证据之间的一致性,不启动服务、不执行 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 目录即可撤回此基础组件,无需迁移用户数据。

@github-actions github-actions Bot added the scope:documentation ./docs/|./*.md|./NOTICE label Sep 10, 2026
@kongche-jbw
kongche-jbw force-pushed the feat/aw/contracts-preview branch from 03b3416 to e01b39c Compare September 11, 2026 08:39
- 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
kongche-jbw force-pushed the feat/aw/contracts-preview branch from e01b39c to e66449d Compare September 11, 2026 08:41
@kongche-jbw
kongche-jbw marked this pull request as ready for review September 11, 2026 10:24
@casparant
casparant merged commit b95908b into agentic-os-org:main Sep 11, 2026
27 checks passed
@kongche-jbw kongche-jbw mentioned this pull request Sep 27, 2026
2 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

scope:documentation ./docs/|./*.md|./NOTICE

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants