AetherContracts 基础规范

本页帮助中文用户理解协议。带标签版本中的英文规范、JSON Schema、测试夹具和 TCK 才是规范性依据。

v1 alpha 的逻辑表示和线编码均为 UTF-8 JSON。核心对象是封闭对象，未知字段会被拒绝。符合要求的原始解码器还必须拒绝重复对象键、格式错误的 Unicode、超过配置档限制的输入，以及无法在契约声明语义下无损表示的 JSON 数字。

整数与其他精确值

协议 uint64 使用规范十进制字符串。字符串不能包含正负号、空白、小数点、指数或前导零；零只能写作 "0"。最大值是 "18446744073709551615"。

Thing Model 可以声明 int64 值类型。Integration v1 alpha 1 把观测到的有符号值冻结为范围 [-9223372036854775808, 9223372036854775807] 内的规范十进制字符串：不接受正号、空白、小数点、指数、前导零或负零。其他模块不会仅因声明 int64 类型就自动获得这套线协议语义。

Integration 观测的十进制数和字节也使用契约声明的字符串，不能经过有损 JSON 数字转换或实现私有的字节强制转换。它们的规范语法、边界和 Base64url 尾随位规则由 Integration 结构定义、英文规范、测试夹具和 TCK 共同冻结。

文本与验证顺序

Integration 的显示文字和证据文字受各自结构定义中的长度限制。内容必须至少包含一个非空白字符，并且不得包含 C0 控制字符（U+0000 至 U+001F）或 DEL（U+007F）。使用方不得把这些字段当成原始终端文字、提供方原始载荷或秘密载体；违反时返回 TEXT_INVALID。

验证顺序属于契约。检查语言绑定输入类型之后，长度超过 20 字节的整数表示必须先返回 INTEGER_OUT_OF_RANGE，再检查数字语法。这样可以限制无分配 C 解码器的资源使用，也能让不同语言对超长对抗输入给出同一结果。

仅通过 JSON Schema 还不够。排序、重放、身份冲突、授权、修订兼容性与持久回执语义需要上下文验证器和 TCK 场景。

JSON 数字

JSON 数字使用有限 IEEE 754 binary64 语义。如果解码后的值为整数，但超出可互操作安全整数范围 [-9007199254740991, 9007199254740991]，只有当 RFC 8785 序列化后仍保留小数点时才可接受；否则生产方必须使用契约声明的十进制字符串。

因此，1e100 与 1.5e20 返回 JSON_UNSAFE_NUMBER，而 1e-100 和 binary64 最大值 1.7976931348623157e308 仍属于浮点值。协议整数不使用这项例外，只使用明确冻结的字符串编码。

资源边界

TCK 严格解码器为嵌套层级、字符串、集合和数字标记设置防御性参考预算。这些默认值是参考实现的安全限制，不是所有实现都必须接受的最大值。只有传输或制品配置档冻结的限制才构成可移植互操作边界；当前 MQTT 配置档把完整消息上限冻结为 262144 字节。其他语言绑定可以采用有记录、更加严格的资源限制，并且必须以 FIELD_BOUND 安全失败。

规范化、摘要与签名

契约定义签名对象时，必须先规定精确签名投影。对象使用 RFC 8785 JSON Canonicalization 序列化，使用 SHA-256 计算摘要，再进行签名。经过美化排版的源文件字节绝不能直接作为签名输入。

基础规范本身不把 CloudLink 认证或签名持久确认提升为生产能力。相关实验性配置档必须分别规定投影、密钥生命周期和一致性证据。

稳定字符串失败代码与语言无关。在未来 ABI 配置档明确冻结之前，数值错误码和错误文字仍属于具体语言绑定的实现细节。

0.1.0-alpha.4 是尚未发布的开发目标，仍处于实验阶段，不是生产协议发布。最新发布版本仍是 v0.1.0-alpha.3。