@agentunion/fastaun 0.5.20 → 0.5.22

package/_packed_docs/sdk/Ownership2.1-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -1,382 +1,322 @@
-# Ownership 2.1 SDK 开发与移植指南
-
-本文面向实现或移植其它语言 SDK 的作者，以当前工作区的 Node TypeScript SDK 为实现参考，说明内部职责、文件验证、条件提交、P2P 编排、持久化与验收。应用如何发起操作及处理审批，见 [SDK 应用集成指南](Ownership2.1-SDK应用集成指南.md)；编排契约见 [SDK 编排指南 2.1](Ownership-SDK编排指南2.1.md)，完整文件格式和服务端授权要求以 [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md) 为准。
-
-设计依据还包括 [Ownership 2.1 详细设计](Ownership2.1详细设计.md) 与 [TDD 分阶段实施计划](Ownership2.1-TDD分阶段实施计划.md)。下文分别说明协议要求和 TypeScript 的实际接线；设计要求不能直接作为某个运行环境已经验收的证据。TypeScript 是接线与组织方式的参考，不是全部差异的默认裁决版本；各项以协议和冻结契约为准，逐项采用哪个 SDK 的正确行为见 [审查报告第十二节](../audit/Ownership2.1代码审查报告.md#十二2026-10-11-本轮复审与修复)和[审查报告第十三节](../audit/Ownership2.1代码审查报告.md#十三2026-10-13-审查更正与最小修复验收)。旧集成、实现指南中的 proof、自动 escrow 和 bindAid/bindOwner 流程属于 legacy；协议 3.0 不在本文范围。
-
-参考包在 [ts/package.json](../../ts/package.json) 中标为 `@agentunion/fastaun`、`0.5.19`，运行要求为 Node `>=22.16.0`。这些是工作区标识，不表示本文描述的 2.1 实现已发布到该版本的软件包。
-
-兼容方向为新服务端保留旧 SDK 的既有身份认证、普通名片、通信及 legacy owner 操作；新 SDK 的 2.1 关系操作不兼容旧服务端，不要求新 SDK 源码调用形态兼容。旧注册、绑定、转移、查询和解绑 RPC 以隔离的 Auth JSONL 和 NS `ownership_proof` 承载兼容状态，不生成 2.1 双文件，不构成 2.1 授权、owner 锁、版本或共识；不得覆盖已存现代声明，见 [协议开篇与 §3.2](../protocol/Ownership协议定义2.1.md#32-判定顺序)。
-
-## 1. 实现边界与角色
-
-| 名称 | 在实现中的含义 |
-| --- | --- |
-| `sub_aid` | 被管理身份，也是自己 `agent.md` 的签署者、认证上传者。 |
-| `owner_aid` | 绑定时为目标 owner；释放、转移任务中为当前／原 owner。 |
-| `new_owner_aid` | 仅用于转移，表示原 owner 授权的目标；必须不同于 `owner_aid`。 |
-| NS | 以同一数据库事务和 CAS 持久化 sub 的权威 `agent.md` 与同步待办，根据该名片和 owner 的权威 `owner.md` 验证当前关系。 |
-| Storage | 保存 owner 的权威 `owner.md`，以及 NS 验收后同步的 sub 名片副本。 |
-| SDK 任务 | 某一个身份的本端工作记录；审批、文件、通知及清理可分别恢复。 |
-
-通用关系各方只签署、上传自己的文件：sub 向 NS 上传 `agent.md`，owner 或新 owner 向自己的 Storage 发布 `owner.md`，不得用 owner 登录态代签或代上传普通 sub 名片。Group/Org 只在作为被管理的 `sub_aid` 时排除于通用 Ownership；符合普通 owner 规则时，仍可作为 `owner_aid`。实体自身关系由专属生命周期建立、解除、转移，不进入通用任务、审批或 NS Ownership 关系状态；以 Group/Org 为 `sub` 调用任务 Facade 时以 `not_applicable` 错误结束（`retryable=false`，按语言表现为异常、Promise reject 或 Go error），共识检查则返回 `status/code=not_applicable` 的结果对象。
-
-Ownership 是 `agent.md` 上叠加的可选关系属性。基础名片解析、普通读取和外层签名验证应与关系验证分层；仅 Ownership 字段或关系材料无效，不得据此判定基础 `agent.md` 无效。关系为 `invalid` 或 `unavailable` 时，只停止或降级依赖当前 owner 关系的授权、共识和关系操作；普通 `agent.md` 下载、基础验签及通信继续。普通读取兼容没有 Ownership 专用 Header 的旧 SDK；新 SDK 的关系操作仍执行当前协议验证。
-
-Group/Org 名片由实体私钥生成主签，当前 owner 以本人 token 上传，无需实体登录；可选一个或多个 owner 附签，每个都须为当前 owner，存在就必须验全部块。Group 旧实体单签及实体身份上传始终兼容，Org 不开放该旧入口。取消实体额外 V2 上传授权，保留当前 owner、生命周期、实体证书代际与 CAS 检查，见 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传)。 实体 fresh GET 必须同时携带 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache`、`X-AUN-Signature-Format: multi-v1`；NS 仅凭 Check 头绕过 LRU 并新鲜验证全部签块，仍返回 not_applicable，不进入通用 Ownership 账本。 fresh GET/HEAD 保留 current/stale、权威 owner/实体指纹头与对应表示 ETag；真正缺失为 404，权威依赖失败为 503。verified 下载逐块验证历史证书及原字节，历史成功不代表当前权限。
-
-关系通过现有 `GET/HEAD/PUT /agent.md` 和通用 Storage 操作建立；不新增 ownership 专用 RPC。SDK 的请求、同意、拒绝和 ready 消息是普通加密 P2P 载荷，不是服务端关系授权接口。托管是应用显式选择的能力，绑定、释放和转移均不以托管为前提。
-
-Ownership 2.1 关系事实只来自 sub 的权威 `agent.md` 与 owner 签署的权威 `owner.md`；后者保存在 owner 自己的 Storage，发布前重新核对完整原文、摘要和存在性。`owner_aid` 是身份字段，不是独立文件或 2.1 关系记录。NS 的数据库事务只保证 `agent.md` 原文、ETag CAS 与同步待办的原子性，不另存 2.1 关系表、证据事实库或历史账本。legacy Auth JSONL 不参与 2.1 判断。CA、P2P、Storage 与 SDK 本地任务分别执行；再次读取当前材料不能制造跨服务一致快照，也不提供 ABA 或完整文件回滚检测保证。
-
-## 2. 分层与最小依赖接口
-
-TypeScript 将语义集中在两个模块，Client 负责装配已有能力。新语言 SDK 可以采用自己的类和命名，但必须保持以下职责分离。
-
-| 层次 | TypeScript 实现索引 | 移植时保持的职责 |
-| --- | --- | --- |
-| 文件模型与验证 | [ownership-v21.ts](../../ts/src/ownership-v21.ts)：`parseOwnershipFile`、`verifyOwnershipFile`、`signOwnershipFile` | 原始字节、两种文件角色、严格 schema、签名与证书状态。 |
-| 本端文件步骤与共识 | 同文件：`OwnershipFiles` | 五个内部文件方法、原条件重试、六态检查、条件清理。 |
-| Storage 适配 | 同文件：`OwnershipStorageAdapter` | 权威存在性、前后完整原文及摘要核对、完整文件原子发布和清理前复核。 |
-| 编排 | [ownership-workflow.ts](../../ts/src/ownership-workflow.ts)：`OwnershipWorkflow` | 固定任务、审批、inbox/outbox、串行推进和事件。 |
-| NS HTTP 与普通名片 | [agent-md.ts](../../ts/src/agent-md.ts)：`AgentMdManager` | 新鲜读取、完整原文条件 PUT、普通待上传恢复。 |
-| 通用签验与业务 Schema | [aid-store.ts](../../ts/src/aid-store.ts)、[cert-utils.ts](../../ts/src/cert-utils.ts)、[agent-md-schema.ts](../../ts/src/agent-md-schema.ts) | Store.sign/verify、AID 兼容包装、agent.md 与 owner.md 统一复用唯一 signDocument/verifyDocument core；YAML/资源身份由调用者另验，服务端独立实现同构 core。 |
-| 当前证书 | [auth.ts](../../ts/src/auth.ts)：`AuthFlow.resolveOwnershipCertificate` | 精确证书、链、当前可签状态及严格 OCSP。 |
-| Client 接线 | [client.ts](../../ts/src/client.ts)：`_getOwnershipFiles`、`_getOwnershipWorkflow` | 本端身份、HTTP、Storage、消息、事件和连接恢复。 |
-| 本地任务存储 | [keystore/index.ts](../../ts/src/keystore/index.ts)、[local-token-store.ts](../../ts/src/keystore/local-token-store.ts)、[aid-db.ts](../../ts/src/keystore/aid-db.ts) | 按身份隔离的每任务 CAS；失败与不存在分开。 |
-
-`OwnershipFileDependencies` 的最小能力如下。不要让文件层依赖界面、P2P 审批或其它服务的源码。
-
-| 依赖 | 必须提供的语义 |
-| --- | --- |
-| `currentAid()`、`now()` | 本端加载的签名身份；Unix 秒时钟，测试时可固定。 |
-| `readAgentMdFresh(subAid)` | NS 当前完整原文、原 ETag、协议、关系版本、锁及观察时间。 |
-| `submitAgentMdRaw(subAid, raw, condition)` | 本人身份上传持久保存的完整签名字节；携带唯一原条件，并回源确认。 |
-| `readOwnerMd(ownerAid, subAid)` | 规范路径的权威存在／不存在结果、完整正文及摘要。 |
-| `writeOwnerMd`、`deleteOwnerMd` | 本人身份、发布前起始原件核对、完整原子写入；删除前核对当前 NS 和本任务原件。 |
-| `resolveCertificate(aid, fingerprint, purpose?)` | 精确证书及已验证的当前链、吊销、生命周期和新鲜度；未知用途可省略。 |
-
-`OwnershipWorkflowDependencies` 只再加入本端 AID、任务存储、文件层、`send` 和 `emit`。TypeScript 的 `send` 调用 `message.send`，设置 `encrypt: true`；`emit` 进入本地 dispatcher。各服务独立实现自己的网络契约，不 import SDK 或共享服务实现代码。
-
-五个文件方法 `declareOwneraid`、`declareSubaid`、`revokeOwneraid`、`revokeSubaid`、`transferOwneraid` 接收内部任务上下文，供编排器复用；它们不创建新 `operation_id`、不发起审批，也不是应用 Facade。`cleanupOwnerFile` 是内部后续清理步骤。
-
-## 3. 标识、版本与数值
-
-| 值 | 校验与用途 |
-| --- | --- |
-| 完整 AID | 非空、完整小写；角色、资源路径、证书 AID 和认证身份分别核对，不能靠大小写转换接受错误材料。 |
-| `operation_id` | SDK 生成的小写 UUIDv4，关联各端同一次编排和重试；只在任务与 P2P 中使用。 |
-| `declaration_id` | 每份声明的小写 UUIDv4；不等于 `operation_id`，也不要求两方相同。 |
-| 名片 `version` | 字符串 `MAJOR.MINOR.PATCH`，描述名片，不是关系版本。 |
-| `statement.version` | 整数 `2`，表示声明容器。 |
-| NS 协议能力 | 字符串 `2.1`，通过响应头确认。 |
-| P2P `sdk.v1` | `aun.ownership.sdk.v1` 中的版本，只表示 SDK 消息格式。 |
-| NS 关系版本 | `0..9007199254740991`；只投影 `agent.md` 当前声明版本，无声明时为 `0`，不另存历史上界。 |
-| 声明关系版本 | `1..9007199254740991`；新绑定为当前可见声明版本加一，无声明时从 `1` 开始；转移为当前声明的 `v+1`。 |
-
-释放任务的目标版本沿用当前声明 `v`，release 或权威删除只解除该声明，NS 不递增版本；普通更新和重复检查也不递增。清理名片关系字段后，响应版本为 `0`，再次绑定从 `1` 开始。例如绑定 `0→1`，释放仍为 `1`，清理后 `0`，再次绑定 `1`；从版本 `1` 转移则直接到 `2`。版本不是跨清理周期的全局代际，旧任务还须匹配完整声明、原文件摘要及原 CAS 条件。
-
-释放后再绑定同一 owner，若 sub 的 `agent.md` 仍保留旧声明，须先由 sub 完成已有字段清理，再发布新的 owner declare；SDK 在创建任务或产生副作用前以 `conflict`／`action_required` 提示，避免新 declare 覆盖唯一释放依据。绑定不同 owner 仍可使用当前可见版本 `v+1`；已清理时默认从 `1` 开始。
-
-移植实现应在创建递增任务、构造目标版本前拒绝当前版本已经达到 `9007199254740991` 的操作；不能溢出或使用本语言更大的整数扩展协议；清理关系声明后的版本 `0` 是无声明投影。TypeScript 的 `ownershipInteger` 使用 `Number.isSafeInteger`，文件、消息和持久任务解码另做字段检查。
-
-双方 statement 的 `version`、`owner_aid`、`sub_aid`、`relation_version` 必须一致；`declaration_id`、`declared_at` 可以不同。普通名片更新则必须保留 sub 自己原来的完整 statement，不能重新生成它来代替正文更新。
-
-起始证据统一保存 `base_agent_md={exists,raw,sha256,etag,statement|null}` 与 `base_owner_md={exists,raw,sha256}`。非空 statement 完整相同的普通正文更新不替代关系，尚未签署的本方候选使用新鲜读取的原 ETag；已持久保存的签名字节重试仍沿用其原 CAS，不刷新条件。起始无声明时完整 agent 原文变化则停止旧审批。owner 写前和清理前重读当前完整原文、摘要及存在性，不增加远端条件字段。 base_owner_md 对应 base_agent_md.statement 所指当前/最后 owner 的文件；无 statement 时没有当前 owner 事实，本地可省略或使用空标记；bind/transfer 目标 owner 写前原件在待发布文件中另存并复读，不替代原 owner 基线。
-
-## 4. 原始文件、严格解析与签名
-
-### 4.1 容器和角色
-
-文件由 YAML frontmatter、可选 Markdown 正文与连续一或多个尾签块组成。payload 为首块前原始 UTF-8 字节，最多 4096 字节；从首块至文件结尾的整个签名区最多 2048 字节，含分隔与尾白。每块签其之前完整 prefix，首块维持旧正文裸签；末块后及块间只允许空白。
-
-解析器必须拒绝无效 UTF-8、非连续尾签块、重复字段、重复 YAML 键、自定义 tag、锚点、别名和未知 ownership 字段。计数采用 UTF-8 字节，不采用 UTF-16 字符串长度；description/avatar 的字符上限按 Unicode 字符计数。
-
-| 文件角色 | 身份及字段约束 |
-| --- | --- |
-| 通用 `agent.md` | `aid`、目标 AID、认证上传者和证书 AID 均为 sub；必填 `aid/name/type/version`，name/type 为非空白字符串。`owner` 与 `ownership` 同时出现或同时省略；ownership 仅含完整 statement。human 不得声明 owner，包含 self-owner；Group/Org 按第 1 节分支处理。 |
-| `owner.md` | 路径为 `owner_aid:/sub_aids/{sub_aid}/owner.md`；顶层恰为 `owner_aid/sub_aid/ownership`，不要求 name/type/名片 version。statement 与路径一致；ownership 含 statement/action，仅 transfer_owner 另含 transfer。 |
-
-statement 恰含 `version/declaration_id/owner_aid/sub_aid/relation_version/declared_at`。owner 动作为 `declare`、`release`、`transfer_owner`；release 保留被释放的旧关系字段。transfer 恰含 `new_owner_aid/target_relation_version/expires_at`，目标版本等于旧版本加一，期限为正整数 Unix 秒。sub 不得在 agent.md 中放 action 来自行授权解绑。
-
-角色取自请求资源和路径，不取自签名 TAG。TypeScript 的 `parseOwnershipFile` 分别调用 agent schema 和 owner schema；`verifyOwnershipFile` 进一步核对目标、认证 AID、证书 AID 及路径上下文。复用通用名片校验器时，不能给 owner.md 补虚构 name/type/version 来绕过角色检查。
-
-### 4.2 数值词法不能在解析后丢失
-
-关系版本、声明时间、授权期限等字段必须是协议整数。TypeScript 的 `parseFileFrontmatter` 检查 YAML scalar 的原始 `source`；`parseOwnershipMessage` 在 JSON 解析外用保留词法的解析结果检查重复键及版本 token。版本 token 使用 `0` 或无前导零的十进制数字，随后再检查范围及字段下限。
-
-`declared_at`、`expires_at`、签名 `timestamp` 的范围统一为 `1..9007199254740991`，只接受十进制正整数原词法；先检查词法及范围，再转数字或日期。非法时间归 invalid，不能由日期库异常变成 unavailable；表示范围不替代证书有效期、当前时钟及授权未过期检查，不另设年份上界。
-
-新语言不能先把输入转成普通 map 再声称完成严格校验：JSON 的重复键可能已经覆盖，`1.0`、`1e0` 可能已变成整数值。YAML 的 `+1`、`01`、十六进制、显式数值 tag、字符串 `"1"` 和布尔值均不能通过类型转换成为有效版本。Python 须排除 bool 作为 int；Go 等默认浮点 JSON 解码须保留 number token；大整数语言和数据库 BIGINT 仍检查协议上界。
-
-### 4.3 签名输入和摘要分别保存
-
-当前文件签名使用 **ECDSA P-256 / SHA-256**，signature 为严格 Base64 的 ASN.1 DER 签名。不能把 E2EE 或 WebCrypto 返回的固定宽度 P1363 `r||s` 原样写入文件；密码适配器负责 DER 编码、解析和验证，并拒绝多余 DER 数据及非规范整数编码。
-
-agent 的常规输出标识为 `AUN-SIGNATURE-AGENTMD-V2`，owner 为 `AUN-SIGNATURE-OWNERSHIP-V2`，均兼容 `AUN-SIGNATURE` 和协议允许的大写字母、数字、连字符 TAG。各尾块含必填 `cert_fingerprint/timestamp/signature`、可选 `public_key_fingerprint`；附签必含 `signer_aid`，通用容器可读主块可选 signer_aid，但普通 agent.md／owner.md 主块禁止该字段，实体主块显式 signer_aid=target；两个指纹分别是证书 DER、SPKI DER 的 SHA-256。
-
-公开 AIDStore.sign/verify 保留默认 raw detached 签验，并支持 document 多签；TS/JS 为 Promise<Result>。document 不要求 YAML，agent.md／owner.md 只能在同一 core 外叠加各自 Schema、主签身份及授权校验，不能再复制尾签算法。文本及 document 严格 UTF-8；显式 input_type="file"（TS/JS inputType: "file"）读取文件，raw 文件可含任意字节，不猜路径或识别 file://。in_place/inPlace 仅 file + document 且成功后写回；浏览器 File/Blob 只读，FileSystemFileHandle 才可写。完整参数见 [API 手册](06-API手册.md#通用-sign--verify)。
-
-append 保留已有完整链字节，后块签自身起点前全部 prefix；只有已有链末字节非 CR/LF 时补 LF，无旧块仍按首签要求非空正文以换行结束，否则拒绝。TAG 为字面后缀，空串无 TAG，内部传 AGENTMD-V2／OWNERSHIP-V2 短标签，不把 AUN-SIGNATURE 当特殊选项。verify 逐块验证并返回实际顺序的 signatures，数学失败仍保留全部结果，不能只验主签或在附签失败后降级；末端删签可形成有效短链，core 不承诺检测。总尾区仍限 2048 字节。
-
-| 材料 | 用途 |
-| --- | --- |
-| payload 原始字节 | 首块前字节为主签输入；第 i 块签其之前完整 prefix，包含前序完整块与分隔。验签不重新序列化 YAML、换行或 Unicode。 |
-| 完整签名文件 SHA-256 | 包含全部尾块，用于持久文件完整性、上传确认、Storage 完整内容核对与留证。 |
-| NS 原始 ETag | 文档条件值，含服务返回的引号等原表示，保存后原样用作 If-Match。 |
-
-TypeScript 的 `ownershipSha256` 计算完整文件摘要；`AgentMdManager.contentEtag` 当前生成带引号的全文 SHA-256 ETag。移植 HTTP 适配器仍须保存服务实际返回的 ETag，不能把本地重算摘要替代原条件。编辑未签 payload 后可以由本人签署新文件；已保存的待提交 raw 不再规范化或重签。
-
-## 5. 当前证书与吊销验证
-
-通用 Store.verify 默认离线 load 本地公钥／证书，不要求私钥，也不隐式远程 resolve。历史／远端材料通过显式可信 certificateResolver 注入；业务原有 resolver 负责证书链、签署时间或当前生命周期／吊销检查，再交唯一 core 验原字节，既有 agent.md 下载的历史远程验证流程保留。resolver 操作异常保留外层 error，不伪装为坏签名；下述当前证书检查属于关系验收层，不是通用数学验签默认保证。
-
-文件验证不仅要求签名正确，还要求签署证书属于对应 AID、精确匹配证书指纹、链到可信根、P-256 公钥、当前有效且处于 `active_signing`、吊销状态已可靠确认。尾块 timestamp 必须在证书有效期内，不能比当前时间快超过 300 秒；它未被 payload 签名覆盖，不能独自证明历史授权时间。
-
-TypeScript 的 `AuthFlow.resolveOwnershipCertificate` 使用既有 PKI 路径：精确 AID 与完整指纹查询，加 `consistency=authoritative`，读取 PEM 后核对以下响应头。
-
-| 响应头 | 要求 |
-| --- | --- |
-| `X-AUN-Cert-Consistency` | `authoritative`。 |
-| `X-AUN-Cert-Lifecycle-State` | 实际状态为 `active_signing`，不能从 OCSP good 推导。 |
-| `X-AUN-Cert-Fingerprint` | 与本次请求、返回证书 DER 指纹完全匹配。 |
-| `X-AUN-Cert-Observed-At` | UTC RFC3339 时间；过去最多 30 秒，未来偏差最多 5 秒。 |
-
-随后核对证书链，捕获本次链选定的直接 issuer，严格验证已签名 OCSP DER、CertID 的 issuer name/key hash 和证书序列号、ResponderID、状态与时限；只接受该 issuer 亲签，内嵌证书仅认可该 issuer 本身，不接受委派 responder。链获取及 OCSP 接收后使用当时的当前时间，末尾再次核对链有效期，不能把初始时点贯穿网络等待。OCSP `ThisUpdate` 最多过去 30 秒，`ProducedAt` 最多过去 90 秒，未来偏差均最多 5 秒；`NextUpdate` 严格晚于当前时间及 ThisUpdate。90 秒窗口包含现有 CA 对 ProducedAt 的分钟取整；不放宽其它当前状态窗口。整个验证窗口也不能超过 30 秒，NS 最终提交仍独立复核其当前材料。
-
-`OwnershipFiles.verifyFile` 按实际签名身份查询当前证书；未知身份用途可省略，owner.md 的 owner 未知类型时不能强制普通 signing。Group/Org 主签证书属于实体并匹配当前实体指纹，可选 owner 附签同样必须验证，不替代当前生命周期授权。Client 通过 `_resolveOwnershipCertificateGateway` 选择证书所属域。缓存证书或 peer 验签成功不等于本次权威状态验证成功。
-
-**CRL 的当前实现边界：** Ownership 上述 resolver 实际走严格 OCSP，没有额外调用通用 Auth 的 CRL 检查。`auth.ts` 中 `_verifyAuthCertRevocation/_fetchGatewayCrl` 属于另一条通用路径，存在 DER 解析失败后的 JSON revoked_serials fallback；通用比较还涉及小写字符串匹配，不能据此声称所有历史序列号表示均已兼容。移植者若使用 CRL 实现吊销适配，应验证签发者、签名、适用范围、新鲜度和序列号对应关系；无法验证的材料不得默认成“未吊销”，也不能用未经验证的 JSON 列表替代 Ownership 的当前吊销契约。
-
-已知错误证书、坏签名、无效链、吊销或非可签状态归为 `invalid`；缺少权威头、OCSP unknown、服务不可达或材料过期归为 `unavailable`。历史任务审计保存当时完整文件和本端验证材料，不要求历史证书今天仍可签名；这些记录不是 NS 当前关系事实。当前释放状态仍从 `agent.md` 与 owner 路径的新鲜材料判定，NS 不保存释放终局；服务或验证材料不可确认时返回 `unavailable`，不能用历史结果代替。
-
-## 6. NS HTTP 与六态共识
-
-每个 NS GET/HEAD/PUT（含 fallback、fresh 与重试）必须携带 X-AUN-Signature-Format: multi-v1；无头时多块投影为 raw[:first.End]（首块 --> 后立即结束），单块保留首签原文，并将 `<!-- AUN-SIGNATURE-<TAG>` 规范化为旧 SDK 能识别的裸 `<!-- AUN-SIGNATURE`，移除首签块中不参与摘要签名的 `signer_aid` 行。投影不改变正文、签名或证书指纹，也不改变完整存储。NS 保留完整存储，Vary、ETag、Content-Length 与 304 按表示区分；旧 If-Match 先匹配旧表示，再映射完整存储快照 CAS，不能把投影摘要当完整文件条件。agent_md_updated.etag 固定完整存储 ETag。
-
-`AgentMdManager.readOwnershipFresh` 经 `_ownershipRequest` 同时发送 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache` 与 multi-v1，严格读取 UTF-8 正文，禁止自动重定向。协议还允许新鲜 HEAD；TypeScript 此入口实际使用 GET。浏览器移植须确认 CORS 暴露关系头和 ETag，否则不能把读不到头当成默认值。
-
-该 Header 用于 Ownership 共识的新鲜读取，不是普通 `agent.md` 读取、下载或基础验签的前提。旧 SDK 普通读取缺少该 Header 时 NS 必须兼容；不得因缺少关系 Header 阻断普通名片，或据此推断 Ownership／名片无效。
-
-| 响应头 | 校验 |
-| --- | --- |
-| `X-AUN-Ownership-Protocol` | 精确为 `2.1`。 |
-| `X-AUN-Ownership-Version` | 严格十进制整数，范围 0 到协议上界；只投影 `agent.md` 当前声明版本，无声明时为 `0`。 |
-| `X-AUN-Ownership-Lock` | 仅 `locked/unlocked`，由当前两份权威材料判定，不是数据库中的独立关系事实。 |
-| `ETag` | 文件存在时必填，保留服务原始值。 |
-
-可靠初始 404 必须来自正确 NS 且携带 2.1、版本 `0`、`unlocked` 的完整元数据。TypeScript 对没有协议头的路由 404 可以尝试既有 NS URL，再校验最终响应；不能将任意网关 404、数据库失败或缓存 404 认定为 unbound。编排发起还要求初始名片已发布；可靠初始不存在本身不足以直接开始绑定写入。
-
-`submitOwnershipRaw` 要求本端身份、目标 AID、名片 AID 一致，持久原条件恰为 `if_match` 或 `if_none_match: '*'` 之一，验证完整已签文件后提交，最后新鲜读取确认完整原文。新 SDK 发布包含普通更新与群名片，已有文件使用原 If-Match，首次创建使用 If-None-Match；2.1 关系和现代实体格式缺条件返回 428，文档冲突为 412，关系版本冲突为 409。NS 旧客户端旧格式入口可缺新 Header/CAS，但仍执行名片数据库 CAS、两份权威材料的关系校验和当前声明版本保护；新上传严格校验，旧关系正文更新保留原关系字段。四 SDK 将 HTTP 428 统一映射为 `unsupported_protocol`；合规 SDK 必须始终携带原条件，收到 428 时不得移除条件或降级重试。TypeScript 的 raw 提交把 409/412 映射为 `conflict`、401/403 为 `forbidden`；不要用设计中的细分错误替代实际 HTTP 适配行为。
-
-`OwnershipFiles.checkConsensus` 的顺序是：新鲜 NS 原文及元数据 → 当前规范 owner 文件及证书 → 再次新鲜 NS。TypeScript 前后比较全文、ETag、存在性、关系版本、锁及可选 owner 元数据，且总窗口不超过 30 秒，从首次 GET 发出前计时，覆盖首读及两种末读分支；材料变化或超时返回可重试 unavailable，不能返回 consensus。仅文档 ETag 相同不足以证明 owner 未释放。
-
-| 六态 | 判定及权限含义 |
-| --- | --- |
-| `consensus` | NS 锁定、NS 版本与双方声明版本一致，AID 和当前签名验证通过；owner declare 或尚未提交的 transfer_owner 均可证明旧关系。 |
-| `released` | `agent.md` 仍有版本 `v` 的声明，对应 owner 文件为有效 release 或已权威确认不存在；前后新鲜观察一致，版本仍为 `v`。 |
-| `unbound` | 新鲜有效的权威名片无当前声明，投影版本为 `0`；释放后清理也属于此态，解析失败不能推断无关系。 |
-| `single_sided` | 只有一方目标材料准备，尚未成为 NS 已验收稳定关系；无 owner 权限。 |
-| `invalid` | 已知字段、身份、路径、版本、签名或证书无效；不解锁。 |
-| `unavailable` | 无法确认当前服务或两份权威材料；保留保护和待办，不等于解绑。 |
-
-以上六态只描述 Ownership 关系及其授权可用性，不替代基础 `agent.md` 的解析和外层签名结果。仅关系字段或关系材料无效时，只对依赖 Ownership 的操作降级；普通名片读取、下载、基础验签和通信不因此失败。
-
-当前 `released` 只表示本次观察确认当前声明已释放，不是 NS 持久终局；字段清理后返回 `unbound/0`。历史 completed 保持历史完成，但不能单独证明当前释放或授权。无目标上下文的公开检查不能枚举全网未提交 owner.md；内部任务已知目标时，检查器才可识别目标 owner 单方声明。转移期限过期只阻止新转移，不使旧关系自动失效。
-
-共识结果携带 `sub_aid/owner_aid/relation_version/lock`、`agent_md_etag/agent_md_sha256`、`owner_md_sha256`，错误可附 `code/reason/retryable`。没有权威观察值时，字段可表示为空；SDK 使用的 `null`、零版本、空字符串或 `unlocked` 等占位值都不代表观察到了版本 0、空摘要或无锁。调用者必须先检查 `status`，只有 `consensus` 或 `released` 才能按对应状态解释权威字段。
-
-## 7. Storage 权威读取、完整发布与权限
-
-四 SDK 的 Ownership Storage 适配器使用通用 `storage.head_object/get_object/delete_object`，发布使用 `storage.create_upload_session` → HTTP PUT → `storage.complete_upload`。读取参数固定 `owner_aid`、`bucket=default`、无前导斜杠的 `object_key=sub_aids/{sub_aid}/owner.md` 与 `consistency=authoritative`。
-
-| 权威结果 | 必须核对 |
-| --- | --- |
-| 所有结果 | `consistency=authoritative`、请求 owner、bucket、规范 path、布尔 exists、observed_at；恢复未就绪不能当权威不存在。 |
-| 文件存在 | 小写完整 SHA-256，以及严格 Base64 的完整 content；现有 object_id/version 不作为读取一致性或共识条件，缺失或无效的可选 version 不拒绝其它有效读取材料。发布时单独要求既有 version 为正安全整数，不能将 null、布尔值或字符串强转为发布条件。 |
-| 文件不存在 | 权威查询明确当前不存在，不从下载失败推断；不保存删除历史。 |
-
-适配器前后重新读取当前完整文件、摘要及存在性，核对完整下载摘要，窗口不超过 30 秒；不一致返回 unavailable。不存在采用权威查询的 exists=false，不依赖公开下载失败。网关错误、超时、权限错误、元数据与正文不同步或恢复未完成都不能作为删除证据。
-
-服务身份须由已认证 Gateway 路由、跨域通道和 RPC 响应绑定证明。当前 wire 不新增“Storage 自报服务证书”字段；TypeScript 适配器从目标域导出 `st.{issuer}` 标签，`OwnershipFiles.readOwner` 核对标签、认证来源、命名空间及路径。这依赖 Client 现有可信路由；新语言不能只拼出相同字符串就宣称完成服务身份认证。
-
-`writeOwnerMd/deleteOwnerMd` 验证本端即 owner。写前重新核对保存的起始存在性、完整原文和摘要；更新为一次完整原子替换，不先删后建。发布 `owner.md` 必须使用 create 返回的会话 URL 完成 HTTP PUT，complete 携带同一 `session_id`；存在时把本次权威读取的对象 `version` 作为 create/complete 的同一 `expected_version`，不存在时使用 `0`。版本缺失或无效不影响只读共识，但不能继续该发布。三阶段保持 Content-Type 一致，complete 提交完整文件的大小、SHA-256 并公开可读；临时对象验证完整且原版本条件仍匹配后才原子替换。沿用既有 Storage 接口，不增加路径修订、哈希条件 RPC 或删除历史；再读不能识别同内容 ABA 或完整文件回滚。
-
-Storage 负责完整文件原子替换；当前 Ownership 写删不传路径修订或哈希条件，写前再读本身不构成跨请求 CAS。上传 session 的既有 `expected_version` 在实际发布时复核，冲突不能刷新版本强行继续旧任务。第三方 ACL、token、目录授权不能获得 owner.md 写删能力；父目录删除、移动、重命名、别名、挂载、软链、批量与自动清理入口都须执行同等限制。SDK 的 requireLocal 不能替代 Storage 服务端权限检查。
-
-起始原件变化时停止旧写入，不更换保存的原件继续。清理仅依据当前 NS 已确认释放／转移及本任务完整旧原件，删除前再读 NS 和目标文件；已观察到后续文件则停止。删除当前 owner 对应的权威 owner.md 可成为 NS 确认释放的依据；删除不表示取消任务。
-
-## 8. 七个 Facade、事件与错误契约
-
-TypeScript 的 [client.ts](../../ts/src/client.ts) 只提供以下七个 2.1 业务 Facade。其它语言可遵循自身命名习惯，返回语义保持一致。
-
-| Facade | 本端角色与行为 |
-| --- | --- |
-| `bindOwneraid(ownerAid)` | sub 发起绑定。 |
-| `bindSubaid(subAid)` | owner 发起绑定。 |
-| `acceptOwnershipRequest(operationId)` | 已核验、待审批的绑定接收方或转移新 owner/sub 同意原任务。 |
-| `rejectOwnershipRequest(operationId, reason?)` | 对同一待审批任务明确拒绝。 |
-| `releaseSubaid(subAid)` | 当前原 owner 发布 release 并新鲜确认释放。 |
-| `transferSubaid(subAid, newOwnerAid)` | 当前原 owner 发起三方连续转移。 |
-| `checkOwnershipConsensus(subAid?)` | 只读六态检查；省略时使用当前身份，不创建任务。 |
-
-TypeScript 前六个方法返回 `Promise<OwnershipTaskResult>`，`checkOwnershipConsensus` 返回 `Promise<OwnershipConsensusResult>`。任务结果包含固定上下文、`status/step` 和可选 `code/reason/retryable`；status 为 `pending/completed/rejected/stopped/error`。`step` 是本端当前步骤，不是 NS 状态。两种结果类型从 [index.ts](../../ts/src/index.ts) 导出；内部 Workflow、任务存储和五个文件方法不因此成为应用入口。
-
-发起前先查找本端身份、发起方、操作、参与方、base/target 版本完全相同的进行中任务，早于新操作资格检查；相同任务复用 ID、审批、原签名字节、条件和期限。精确目标已提交时新鲜核验完整证据完成原任务，同代际不同意图返回 conflict 且不另建 stopped；相同意图并发只保存一个任务。后代际先停止旧任务再创建新合法任务，历史 completed、rejected、stopped、不可重试 error 不作为新操作复用或自动复活。
-
-服务、网络或验证依赖不可用归 `unavailable`，确定无效的文件、签名、证书或证据归 `invalid`。新鲜重读发现远端 NS ETag、关系版本、锁或 owner 完整原文、摘要或存在性已不满足任务保存的原条件，归 `conflict` 并停止旧写入；同一权威快照内部的元数据、正文摘要彼此不一致，以及 Storage Base64 传输封装损坏，归 `unavailable`；摘要匹配后确定非法的 UTF-8、文件字段或签名归 `invalid`。等审批/材料、`unavailable`、`unsupported_protocol` 保持 pending/true；版本替代、目标改变、授权过期、原条件失效为 stopped/false；确定证据无效为 error/false；明确拒绝 rejected/false，完整目标确认 completed/false。预检失败不建任务；本地任务存储/CAS/租约失败归 `persistence_unavailable`，保持已存记录并停止副作用。completed 后通知/清理失败只保存错误和待办，停止前先核目标事实，终态不被迟到消息重启。
-
-| 本地事件 | 语义 |
-| --- | --- |
-| `ownership.request` | 已持久保存并核验的绑定／转移审批请求。 |
-| `ownership.action_required` | release 已提交后，sub 的名片清理需要应用明确授权。 |
-| `ownership.progress` | 本端阶段推进，不能作为关系成立证明。 |
-| `ownership.completed` | 新鲜 NS 目标及本端材料核验匹配。 |
-| `ownership.rejected` | 本次审批被拒绝。 |
-| `ownership.stopped` | 本次推进已停止或被后续版本替代。 |
-| `ownership.error` | 无法推进或核验；completed 后的通知／清理失败也可触发，保留已提交关系及待办。 |
-
-事件直接传 payload，不要求应用读取 `event.params`。载荷包含公共任务字段和 `local_roles`；request 另含可信 `requester_aid`，已核验时附 `relation_version`。这些是 SDK 本地 dispatcher 事件，不是服务端事件类型，也不通过 P2P 转发。TypeScript 的 `emit` 在持久保存后排入 microtask；恢复可能再次通知，应用按 operation_id、事件名、step 幂等处理。
-
-绑定／转移 completed 需要当前双方有效共识、指定 owner 和目标版本；TypeScript `confirm` 还核对本端明确同意，并按本端角色比较自己保存的 agent／owner 全文摘要。释放 completed 接受本任务声明 `v` 的新鲜 `released/v`，或由本任务原件严格关联的真实 `unbound/0` 完成证据；任务起始、目标及历史 verified 版本仍为 `v`。sub 离线或字段未清理不妨碍原 owner 以新鲜 released 完成，历史完成不替代当前关系检查。通知已发送、消息 ACK、ready、relation.confirmed 均不能代替这些条件。
-
-| 业务错误码 | 处理语义 |
-| --- | --- |
-| `owner_locked` | 有效原锁阻止本次改写。 |
-| `conflict` | 原版本、ETag或固定上下文变化，停止旧条件写入。 |
-| `invalid` | 已知字段、签名或证书无效。 |
-| `unavailable` | 当前事实无法确认，可保留任务等待。 |
-| `unsupported_protocol` | 缺少 2.1 能力或遇到 legacy，不能降级写入。 |
-| `persistence_unavailable` | 任务保存／读取失败或损坏，停止外部副作用。 |
-| `forbidden` | 本端身份、参与角色、来源或消息方向不符。 |
-| `operation_not_found` | 审批找不到对应本端任务。 |
-
-任务结果的 `code` 是业务字符串；抛出的 TypeScript `AUNError` 用 `stringCode` 表示业务码，`code` 是数值 RPC 码，`retryable` 在错误实例上。Workflow 的 `drive` 将部分推进失败写入结果并发事件，持久化错误会向外抛出；不能假设每次调用只返回结果或只抛异常。六态 status 也不等于任务 status；例如缺协议能力可以得到 `status=unavailable`、`code=unsupported_protocol`。
-
-当前没有公开 2.1 任务查询、取消或 force unlock Facade。测试 HTTP agent 的 status/events 路径是测试适配器，不能照搬成新的 SDK 或 AUN 服务端接口。
-
-## 9. P2P 载荷与实际收件拦截
-
-控制载荷 type 固定为 `aun.ownership.sdk.v1`，必含 `operation_id/operation/action/sub_aid/owner_aid/base_relation_version/target_relation_version`；operation 为 bind/release/transfer；bind、transfer 的目标版本等于起始版本加一，release 的目标版本等于起始版本。transfer 必含 new_owner_aid，其它操作省略。reason 只允许在 reject 或 operation.stopped 中出现；未知、缺失字段拒绝。
-
-| action | 合法发送方向 |
-| --- | --- |
-| `bind.request` | sub 或 owner → 另一绑定方。 |
-| `bind.accept/bind.reject` | 原请求接收方 → 发起方。 |
-| `transfer.request` | 当前原 owner → 新 owner、sub。 |
-| `transfer.accept/transfer.reject` | 指定新 owner 或 sub → 原 owner。 |
-| `transfer.ready` | 原 owner → 新 owner、sub。 |
-| `owner.ready` | bind 的 owner 或 transfer 的新 owner → sub。 |
-| `relation.confirmed` | bind/transfer 的 sub → 其它参与方；release 的原 owner → sub。 |
-| `sub.cleaned` | release 的 sub → 原 owner。 |
-| `operation.stopped` | 已有关联任务的参与方 → 其它参与方。 |
-
-发送采用加密持久 `message.send`，不设置 volatile TTL。来源只取消息层验证的 from_aid；不相信载荷自报身份，也不接受发给自己的 P2P。`parseOwnershipMessage` 联合本端角色、原任务发起方、固定 AID/版本、审批与 NS 现状校验方向。ready 还要求本端已同意，并回源验证原 owner 授权与目标声明；relation.confirmed 必须回源确认目标结果。
-
-TypeScript 的拦截链为 [v2/e2ee/decrypt.ts](../../ts/src/v2/e2ee/decrypt.ts) 保留解密 JSON 原文 → Client `_publishAppEvent('message.received')` → `_handleOwnershipMessage` → `OwnershipWorkflow.receive`。`decryptedOwnershipJsonText` 保留词法，控制来源通过解密后的 from_aid 传入。实时 push、离线 pull、重连补拉和排序消息都必须经过同一入口。
-
-被识别为 `aun.ownership.*` 的 legacy type、未知 action、无效控制载荷由拦截器消费，不作为普通聊天消息投递。有效控制消息首先按已认证发送者、operation_id、action 保存 inbox；存储失败向调用链抛出，原待解密／有序／补拉消息必须留在原处。只有可靠保存成功，才能移除原消息、推进游标、标记已投递、发送 ACK。禁止把保存失败改成普通 message.received 或不可解密通知。
-
-[client/delivery.ts](../../ts/src/client/delivery.ts) 的 `publishOrderedQueueItem`、`publishPulledMessage` 等路径会等待 Client 事件拦截；移植时要检查实际 delivery 调用链，不能只为一个 handler 写正确代码却在其返回前 ACK。收件去重不要求网络恰好一次；重复或乱序提示回源后仅补尚未完成步骤，迟到消息不能改目标或重启拒绝／停止任务。
-
-## 10. 持久任务、审批与恢复
-
-### 10.1 存储契约
-
-TokenStore 提供 `loadOwnershipTask(aid, operationId)`、`listOwnershipTasks(aid)`、`compareAndSwapOwnershipTask(aid, operationId, expectedRevision, task)`。不存在返回 null；读取、解析、CAS 失败必须返回错误。expectedRevision 为 null 表示仅首次插入，后续更新比较原任务修订并递增。
-
-TypeScript `AIDDatabase` 使用 `ownership_tasks(operation_id, revision, data)`，`BEGIN IMMEDIATE` 内读取、比较、写入并提交，LocalTokenStore 按身份定位数据库。本地任务修订与文件中的关系版本独立。进程内 `runSerialized(subAid)` 只负责本实例排序；数据库 CAS 防止旧任务快照覆盖。不能将全部任务放在一份易覆盖的 metadata JSON 中，也不能把损坏数据库自动重建成“没有任务”。
-
-| 记录分组 | 必须持久保存的内容 |
-| --- | --- |
-| 固定上下文 | operation_id、operation、参与 AID、起始／目标版本、发起方、本端角色。 |
-| 审批 | local_decision 的 pending/accept/reject、按 AID 保存的 approvals；发起意愿与接收方决定分开。 |
-| 文件 | 本人完整已签 raw、全文 hash、原 NS ETag 与起始双文件证据；接收方首次验证转移授权的全文摘要 authorization_sha256 和实际 expires_at，恢复不允许换字节或延期。 |
-| 收件 | inbox 与 received 幂等键，不能因远端失败丢掉原收件。 |
-| 发件 | outbox 的接收 AID 与原载荷、已安排通知标记。 |
-| 结果及清理 | status、step、verified_relation_version、清理授权引用、旧对象条件、最近错误。 |
-
-审批决定与待发送回复在同一次 CAS 中保存，然后发送；本方文件 raw/hash/condition 也先保存再写远端。发送成功后再 CAS 清除 outbox，若发送后保存失败则可能重发，接收方必须幂等。当前 TypeScript outbox 保存 to/payload，不应宣称已经持久保存传输 message_id。
-
-`decide` 只批准已核验、本端未决定的 bind/transfer 请求；不能批准自己发起的任务，也不能将 accept 改成 reject。原 owner 按审批 AID 收齐转移同意，角色重合以唯一 AID 计决定；尚未决定的另一方拒绝仍结束任务，迟到回复不覆盖已持久决定。
-
-`decode` 校验任务身份、固定参与方、版本、角色、审批及集合；completed 还要求持久验收证据包含验收时的 NS ETag、agent.md 全文 SHA256、实际 lock／owner／relation_version，并按本端角色保存本人已签原始完整字节、摘要和原提交条件。bind/transfer 的核验版本等于目标，另须有 owner.md 全文 SHA256及本端同意；release 的任务起始、目标及历史 verified 版本仍为 `v`，真实完成证据保存 `released/v` 或严格关联本任务的 `unbound/0`，不得伪造 released。sub 的 unbound 证据须对应本任务清理原件、摘要、原 CAS，或本人明确 accept 的原 bind/transfer 的匹配 `release_cleanup`，并核对当前 NS 原文、摘要、ETag及已知提交 ETag；owner 须以本任务 release 完整原件、摘要与当前 owner.md 全文、hash 一致且当前证书验证有效确认，不得补造旧条件。权威不存在的 released 证据中 owner 文件摘要可为空。该记录只证明任务当时完成，当前关系仍须重新读取两份权威材料；清理后的 `unbound/0` 不保留历史版本上界。本人原件还须按文件角色、签名者、owner/sub、base/target、action、转移目标/期限及原条件匹配任务固定上下文；历史复验不要求现在仍可签或授权未过期。缺失、损坏证据的旧 completed 返回 persistence_unavailable，不能只看 step 或 completed 字符串跳过，也不能读取当前网络补造历史证据。合法历史完成记录可保留，当前 NS 已进入后续版本不使它变成新的待写任务。
-
-### 10.2 恢复顺序与失败重试
-
-TypeScript `resume` 读取原任务，按 sub 串行 `drive`，实际顺序为 `processInbox → flush → 按分支 confirm／推进／清理`。`flush` 在发送每条待办前读取新鲜 NS，按 action 核对原关系或目标关系的完整声明、版本、锁和 owner；陈旧通知从 outbox 移除并持久保存，无法确认时保留待办，不发送。未完成任务的 transfer.ready 另核对持久授权期限。待审批请求重新发本地事件，仍为 pending；不能因为连接恢复或等待超时自动同意。通知发送本身不证明关系完成，后续处理和完成判断仍须核对新鲜 NS。
-
-| 中断位置 | 恢复依据和行为 |
-| --- | --- |
-| 审批已保存、回复未发或发送后未清 outbox | 先新鲜核对该 action 所需原关系或目标关系，再按原 operation_id、决定和载荷重发；陈旧通知持久移除，发送本身不确认关系完成。 |
-| 文件已签但未发布 | 复用已保存原始字节与原条件；不换 declaration_id、时间或签名。 |
-| owner 写入响应丢失 | 当前完整 raw/hash 与本任务已签文件匹配则仅确认；否则仅在保存的起始存在性、完整原文和摘要仍匹配时重传。已观察到变化返回 conflict，不从网络补造起始证据。 |
-| sub PUT 响应丢失 | 若尚未持久化本次发布的 NS `agent.md` ETag，只有新鲜核对指定 owner、目标版本、锁及完整原文件均匹配时才能确认并保存该 ETag；若已持久化 ETag，当前 ETag 和完整文件必须匹配，ETag 变化即使原文相同也返回 conflict。未确认发布时，仅在原 If-Match／If-None-Match 条件仍成立时重传；仅版本增加不足以证明成功。 |
-| 当前路径不存在 | 与保存的起始存在性核对；起始文件原先存在而当前不存在时停止旧写入。不能据当前文件判断同内容 ABA 或历史回滚。 |
-| release 已发布、NS 暂不可用 | 保留 release 与确认待办，恢复后请求新鲜 NS 检查。 |
-| 已有后续版本、ETag 或完整原件变化 | 停止旧写入／删除，保留真实结果及错误；不能更换起始原件或刷新 NS 条件强行续写。 |
-| 转移期限到期 | 不延期重签，不自动 release 再 bind；继续须新的明确发起和审批。 |
-| 关系已提交、通知／旧文件／副本仍待处理 | 保持已提交关系，分别补发、条件清理或由 NS 补齐副本。 |
-
-TypeScript 的 `publishOwner` 固化起始存在性、完整原文和摘要，连同已签 raw/hash 持久保存，实际发布前再次核对原件；`publishAgent` 固化 NS 原 If-Match／If-None-Match 条件，连同已签 raw/hash 执行 `task.persist()`。重试沿用原件、原字节与 NS 原条件。恢复不能调用 bind/transfer 发起接口代替 resume，因为每次新发起通常生成新 UUID。停止消息只停止后续推进；不能撤回已发布转移授权或已提交关系。撤回未提交授权是原 owner 核对当前完整原件后原子覆盖为同版本 declare 并新鲜确认，不是删除文件，也没有独立取消 Facade。
-
-Client `_connectOnce` 通过 `_safeAsync(_resumeOwnershipAfterConnect())` 异步安排身份检查、注册意图和 Workflow 恢复。`await connect()` 不等于所有 Ownership 待办已经恢复完成；实现和应用应以对应结果／事件及 NS 新鲜事实判断。
-
-## 11. 三种流程与 self-owner
-
-| 流程 | 默认编排和最终依据 |
-| --- | --- |
-| 绑定 | 发起方保存意图和 request；接收方保存同意；owner 用 declareSubaid 发布 `v+1`；sub 用 declareOwneraid 自签 PUT；NS 验收后各端新鲜确认。 |
-| 释放 | 原 owner 用 revokeSubaid 条件发布当前版本 `v` 的 release；NS 动态确认 `v/unlocked`，不另存关系或递增版本；通知 sub，字段与旧文件分别清理。真实权威不存在同样可确认该声明释放。 |
-| 转移 | 原 owner 发 request；新 owner 与 sub 同意；原 owner 用 transferOwneraid 发布旧版本授权；新 owner 发布 `v+1` declare；sub 自签提交 `v+1`；NS 条件提交目标名片，随后从两份权威材料确认及条件清理旧文件，不另存关系或证据表。 |
-
-审批阶段不写协议文件。默认编排给出易恢复的步骤顺序，协议本身允许各方乱序独立发布；NS 不维护跨方 prepare 或等待任务。转移授权绑定旧关系、指定新 owner、目标版本及有效期，不依赖另外两方预交目标文件或摘要。TypeScript 首次授权采用本地 3600 秒，持久保存实际 expires_at；恢复不延长它。
-
-释放后的 sub 自动清理只使用本端明确 accept、包含 sub 角色、本人已签 agent 中 owner/sub/被释放的完整 statement（含 declaration_id、版本）完全匹配的原 bind/transfer 记录；转移历史匹配目标 owner。收到 release 通知时，因发布响应丢失仍 pending 的原任务也可提供该授权；无控制消息时，仅已完成历史任务的恢复路径触发自动清理，即使没有 relation.confirmed，也须新鲜核对权威释放事实。清理原件、全文摘要和原 CAS 单独持久保存，保持历史 completed 及原完成证据。字段已清空时不签写；响应丢失复用原件/条件，全文、ETag及已知提交 ETag 均对应原清理提交时只观察确认，冲突保留待办。没有该授权且仍有旧字段时，任务保持 pending 并发 action_required；acceptOwnershipRequest/rejectOwnershipRequest 不接受 release 任务，应用可通过已有名片 API 明确签署清理文件。
-
-若新鲜有效名片的关系字段已经清空，sub 只有以本任务持久清理原件、摘要及原 CAS，或本人明确 accept 的匹配原 bind/transfer.release_cleanup，精确核对当前 NS 原文、摘要、ETag及已知提交 ETag 后，才可仅观察本任务清理完成，无需再签写或审批；空字段本身不证明本任务完成或本端同意。原 owner 的释放任务可早已 completed，历史绑定／转移 completed 也保持原记录；当前关系检查返回 `unbound`，响应版本为 `0`，任务版本仍为 `v`。NS 不保存释放终局或历史版本上界；后续绑定和旧任务恢复须重新核对完整文件与原条件。
-
-self-owner 为 owner_aid 等于 sub_aid，同一身份按两个角色分别签自己的 owner.md 和 agent.md；不减少文件、签名或 NS 验收要求，不添加特殊状态。应用本端发起可覆盖本端角色意愿，SDK 不向自己发 P2P；转移中 sub 与新 owner 重合时合并对同一 AID 的请求和决定。
-
-self-owner → 外部 owner 仍需当前身份的原 owner 授权及目标 agent.md，外部新 owner 的目标 owner.md；外部 owner → self-owner 仍需原外部 owner 授权及 sub 的两个目标文件。原／新 owner 相同不是有效转移；已有外部锁不能凭两个 self-owner 文件绕过。
-
-## 12. 普通／群名片、注册与兼容边界
-
-普通 2.1 名片更新保留当前完整 owner 和 statement，使用新鲜 NS 原 ETag 与本人当前签名上传，不递增关系版本。已有普通 legacy owner-only、proof 或 2.0 关系的普通名片入口允许仅更新正文；owner、ownership、ownership_proof、ownership_release 的字段存在性、类型和值必须完整保留，新 metadata 和外层签名执行当前上传规则，不由普通更新新建旧绑定或自动迁入 2.1。旧 SDK 的 owner 变更另走隔离的 legacy RPC/operation ID 兼容入口，只激活旧 `ownership_proof`，不覆盖已存现代声明，不生成 2.1 lock/version/consensus。NS 接受名片后再通过受限可信 nameservice 内部 `storage.put_object` 原子同步 `{sub_aid}:/agent.md` 原始签名副本，无需客户端 HTTP 会话；内部镜像只能写本域 `default/agent.md`，不能写删 `owner.md`。副本失败不回滚关系。正文普通更新会改变文件 ETag，即使关系版本不变也要重新同步；副本不能替代 NS 作为授权依据。
-
-四 SDK 普通 `downloadAgentMd`／`download_agent_md` 及文件验签兼容历史 aid-only、无 frontmatter 的已签正文、实体自签及旧关系材料；历史尾签允许 16/64 hex 的 DER/SPKI 指纹、前缀省略、冒号和大小写，时间戳前导零及 CN 去首尾空白／忽略大小写仅适用于 agent.md 历史读取。签名原字节、实际 signer、指纹、证书链及签署时间仍须验证；现代 Group/Org 即使在兼容读取中也要求严格完整 DER 证书指纹、owner 与 entity_cert_fingerprint，主签 cert_fingerprint 必须匹配实体指纹，已出现但无效的指纹不得回退 legacy。旧 Group 读取仅限 type=group、恰一个签名块、无 entity_cert_fingerprint 且主 signer_aid 缺省或等于实体 AID；Org 不开放，上传不采用这些读取宽松规则。读取兼容的证书查询／缓存与通用 Auth、消息及当前 Ownership 验证隔离。`verification.ownership_status` 保留 legacy proof 展示语义，不是 2.1 新鲜共识或授权结果；文件验签成功不代表当前关系，仍须调用 `checkOwnershipConsensus` 及本语言对应方法，业务执行端自行新鲜授权。
-
-普通名片候选先通过本地 schema／外层签名验证，在首次远端 preflight 前独立持久保存私有 `local_draft_content`；不覆盖远端 content/ETag。持有本地私钥的自有身份默认 resolve 优先该稿，返回 unverified、in_sync=false、source.agent_md_fetched=false；显式 download／forceRefresh 仍读取远端权威内容并保留草稿，服务端确认对应候选提交成功后才清稿。失败稿仅本地保留，普通 initial 失败稿同样需要应用显式重试；重连即使发现普通 pending 也不自动重传。`AgentMdManager._uploadPrepared` 取得可靠 NS 条件后，仍在 PUT 前持久保存 signedContent、pending_condition 和 pending_relation（原 owner、完整 statement、relation_version、lock）。显式重试既有 pending 时，`resumePendingUpload` **先检查持久原条件，再读取远端**；缺条件保留原元数据及原错误，即使远端同字节也不清待办。2.1 正文更新核对原版本、锁、owner 和完整 statement；受限 legacy 正文更新另保存可信 base 全文、摘要、原 ETag 及全部旧关系快照，核对 base/candidate/remote 的存在性、类型和值，缺上下文不得补造。当前原文与提交 ETag 均对应原提交时只观察确认，否则仅在原 CAS 和关系仍匹配时重传原 blob，不换条件或重签；关系改变、远端消失或已被 2.1 接管则冲突并保留 pending。其它缺原上下文的旧待办仅允许版本 0／unlocked 的初始关系；Ownership 2.1 任务、消息及 outbox 仍由其既有机制恢复。
-
-Group/Org 名片失败稿及 pending 保留实体命名空间中的完整多签原文、原 CAS、固定 owner 和实体证书指纹，由应用显式重试，post-connect／重连不隐式 PUT。重试先验证完整原件及当前 owner、状态和证书代际，原条件完整且同代际原文／ETag 已确认提交时只观察完成。转移、rekey 或解散后停止旧代际待办，不更换身份、指纹或条件重签。取消实体 V2 授权后，不再保存、刷新或检查其额外授权及过期窗口；普通文件签名与当前证书检查保留。专属 create/transfer 自身 checkpoint 恢复机制不变。
-
-普通主体注册指定 owner 时，[aid-store.ts](../../ts/src/aid-store.ts) 先保存 `protocol=2.1` 的 registration_intent 和固定 operation_id；可靠初始化只发布本人无 owner 名片。初次连接由 `_resumeRegistrationIntent` 复用同一 operation_id 进入绑定，注册成功不是关系已成立。Group/Org 的身份准备由专属生命周期使用，不建立通用注册 owner 意图；已有关系／不可靠读取不能作为重新初始化或清空关系的依据。
-
-旧 `ownership_proof/ownership_release`、只有 owner 字符串而缺少完整 2.1 statement 的文件不能自动降格为 unbound，也不能用旧 records 解锁。TypeScript `OwnershipFiles.verifyFile` 明确拒绝 legacy；`bindAid/bindOwner/releaseOwnership` 抛出带 `stringCode=unsupported_protocol` 的异常，`getOwner/getOwnershipStatus` 仍读取 legacy records，不能作为 2.1 当前关系查询。升级必须明确核验原权威事实，不借迁移清空版本或 owner 锁。
-
-业务执行端仍须认证调用者、目标 sub、权限范围和新鲜共识，绑定 token/ACL 到完整关系声明及其版本并检查当前有效性；清理后版本可重复，不能单凭版本识别关系；客户端事件或布尔值不是授权证明。敏感操作执行前保存完整文件与验证证据。托管私钥和凭据交接由应用另行处理，NS 转移不自动撤销旧私钥、证书、token 的身份能力，也不代表业务交接已经完成。
-
-## 13. 跨语言 TDD 与有序验收
-
-移植从共同向量开始，再接文件层、持久 Workflow 和真实 Client 通路；先用失败断言固定边界，再实现该边界。不要只用当前语言生成的数据验证自己，也不要以纯 Workflow mock 代替实际收件／连接接线。
-
-共同文件是 [tests/vectors/ownership_v21/vectors.json](../../tests/vectors/ownership_v21/vectors.json)，测试向量位于顶层 `documents` 键下；当前包含 **119 个完整文件、51 个消息、24 个六态入口**，固定 verification_time 为 `1791524400`，材料范围标为静态单元夹具。`raw_base64` 必须解码为完整原文；文件解析预期与完整验签预期分别检查。
-
-TypeScript 消费入口为 [tests/conformance/ownership_v21.test.ts](../../ts/tests/conformance/ownership_v21.test.ts)；内部行为参考 [ownership-v21.test.ts](../../ts/tests/unit/ownership-v21.test.ts)、[ownership-workflow.test.ts](../../ts/tests/unit/ownership-workflow.test.ts)、[client-agent-md-api.test.ts](../../ts/tests/unit/client-agent-md-api.test.ts)。随机 ECDSA 不要求各端生成相同签名值，要求签名格式、覆盖字节及跨端验签一致。
-
-| 验收顺序 | 完成后才能进入下一项的证据 |
-| --- | --- |
-| 1. 原始文件与密码 | 双角色、严格 JSON/YAML、字节大小、TAG、整数边界、DER 与完整文件签名；坏材料分类一致。 |
-| 2. 权威适配 | NS 原条件／可靠 404，Storage 当前完整文件与存在性再读、可信来源，精确证书及当前吊销状态；故障不解锁。 |
-| 3. 文件方法与六态 | 自签自传、五个内部步骤、绑定／release／权威删除／连续转移／self-owner；前后 NS 一致性。 |
-| 4. 持久 Workflow | 每任务 CAS、审批与 outbox 原子、未决不自动批准、角色去重、固定期限、损坏完成态拒绝。 |
-| 5. 实际 Client 通路 | 解密 JSON 原文保留、push/pull/reconnect 统一拦截、持久成功前零队列移除／游标／ACK；普通与群待办隔离。 |
-| 6. 中断窗口 | 保存后发送前／后、owner/sub 提交后失响应、release 待确认、后续代际、过期、停止前后；原字节与原条件不变。 |
-| 7. 网络互通 | 单域集成 → 单域 E2E → cross-sdk → pub/cn 双向联邦；轮换 sub/原 owner/新 owner，观察真实 NS、Storage、CA 和凭据身份。 |
-| 8. 服务持久与副本 | 真实数据库中的名片原文、CAS 与同步待办原子一致；服务恢复后从两份权威材料验证关系，副本最终逐字节一致；与 SDK 恢复证据分开。 |
-
-单元测试可以并行，但每项使用隔离的数据库、AID 和目录；共用 Docker 环境仅一个测试名额，按上表的网络顺序串行执行。服务代码改变后，先重新构建、更新对应容器并核对真实运行版本，再运行受影响的网络验收；不能用旧容器结果验收新服务代码。
-
-运行到失败立即停止，保存用例 ID、任务固定上下文、已通过阶段、NS 版本／ETag、文件摘要及日志；修复后先重跑失败项，再从未完成阶段继续。已通过且未受修改影响的项目不重复执行。现有 runner 不存在通用 resume 参数，按 [TDD 第 11 节](Ownership2.1-TDD分阶段实施计划.md#11-测试命令与续跑方法) 的检查点方法续跑；测试环境和命令见 [AUN 测试运行指南](../aun测试运行指南.md)、[分布式指南](../aun分布式测试运行指南.md)、[公网指南](../aun公网测试运行指南.md)。对外地址使用 `{svc}.{issuer}`，Windows Python 使用 `-X utf8`。
-
-当前通过项及未完成／受限项只以 [TDD 第 13.4 节](Ownership2.1-TDD分阶段实施计划.md#134-测试与失败续跑账本)、[第 13.6 节](Ownership2.1-TDD分阶段实施计划.md#136-四-sdk-一致性检查点) 和 [第 13.7 节复审修复验收](Ownership2.1-TDD分阶段实施计划.md#137-2026-10-11-本轮复审修复验收)及[第 13.8 节复查更正与修复边界](Ownership2.1-TDD分阶段实施计划.md#138-2026-10-13-复查更正与修复边界)的具体证据为准：共同向量和本地定向通过不表示真实浏览器联网、当前完整 JS bundle 互操作或所有 SDK 跨 PID 强杀恢复均已通过。SQLite／IndexedDB 连接重开、新建 Workflow、服务独立恢复进程和真正进程重启分别记录。新移植 SDK 应提供自己的目标平台与运行版本证据，不能继承参考实现尚未覆盖的环境结论。
+# Ownership 2.1 SDK 开发与移植指南
+
+面向 SDK 实现者，以 Node TypeScript `0.5.22` 工作区（未发布，发布基线 `0.5.21`）说明文件验证、权威适配、消息持久化和恢复。应用调用见 [集成指南](Ownership2.1-SDK应用集成指南.md)；字段和授权以 [协议 2.1](../protocol/Ownership协议定义2.1.md) 为准，历史兼容见 [编排指南 §8](Ownership-SDK编排指南2.1.md#8-崩溃与响应丢失后的恢复)。
+
+## 1. 实现边界与角色
+
+关系事实仅来自 sub 在 NS 的当前 `agent.md` 和 owner 在本人 Storage 的当前 `owner.md`。sub 自签自传，owner 自签自传；owner 登录态不能代上传普通 sub 名片。NS 事务原子保存名片、CAS 和同步待办，不另建关系账本；SDK 任务只记录本端编排。
+
+普通名片解析、外层验签与关系验证分层。正文更新保留全部关系材料的存在性、类型和值及原 CAS，不以前置共识或 owner Storage 可用为条件；关系字段变更仍执行双文件授权。
+
+Group/Org 作为 sub 使用专属生命周期：通用任务抛出 `not_applicable`，共识返回同名结果；它们仍可按普通 owner 规则作为 owner。现代实体名片由实体主签、当前 owner token 上传，可选 owner 附签且全部验证，详见协议 §2.5。
+
+## 2. 分层与最小依赖接口
+
+| 层次 | TS 参考与职责 |
+| --- | --- |
+| 文件／共识 | [ownership-v21.ts](../../ts/src/ownership-v21.ts)：严格解析、签验、`OwnershipFiles`、权威 Storage 适配。 |
+| 编排 | [ownership-workflow.ts](../../ts/src/ownership-workflow.ts)：审批、每任务 CAS、inbox/outbox、结果和清理。 |
+| HTTP／证书 | [agent-md.ts](../../ts/src/agent-md.ts)、[auth.ts](../../ts/src/auth.ts)：NS fresh／原条件 PUT、精确证书和当前吊销状态。 |
+| Client／存储 | [client.ts](../../ts/src/client.ts)、[aid-db.ts](../../ts/src/keystore/aid-db.ts)：装配身份、消息、事件、重连和持久任务。 |
+
+文件层依赖：`currentAid/now/readAgentMdFresh/submitAgentMdRaw/readOwnerMd/writeOwnerMd/deleteOwnerMd/resolveCertificate`。读返回完整原文、存在性和权威元数据；写使用已保存原字节及原条件。各服务独立实现网络契约，不 import SDK 或其他服务源码。
+
+以下是 SDK 内部装配片段；应用只使用集成指南中的公有 Facade：
+
+```ts
+import { OwnershipFiles } from './ownership-v21.js';
+import { OwnershipWorkflow } from './ownership-workflow.js';
+const files = new OwnershipFiles(fileDeps);
+const workflow = new OwnershipWorkflow({
+  currentAid: () => identity.aid, store: tokenStore, files,
+  send: sendEncryptedMessage, emit: emitLocalEvent,
+});
+```
+
+## 3. 标识、版本与数值
+
+| 值 | 规则 |
+| --- | --- |
+| AID | 完整小写；分别核对资源、证书、路径和认证身份。 |
+| operation／declaration ID | 小写 UUIDv4；任务 ID 与各文件声明 ID 独立。 |
+| 格式版本 | 名片为语义版本字符串；statement.version 为整数 `2`；NS 协议头为 `2.1`。 |
+| 关系版本 | NS 投影 `0..9007199254740991`，statement 从 `1` 起；递增前检查溢出。 |
+
+绑定、转移为当前可见声明 `v+1`；release 保持 `v`；sub 清空关系后投影为 `0`，重绑默认 `1`。版本不是全局代际，旧任务还须核对完整声明、原件和 CAS。双方 statement 的 version、owner、sub、relation_version 相同；declaration_id 和 declared_at 可不同。
+
+持久保存 `base_agent_md={exists,raw,sha256,etag,statement}` 和当前／最后 owner 的 `base_owner_md={exists,raw,sha256}`；目标 owner 写前原件另存。尚未签署的本方候选可使用语义未变正文的新鲜 ETag，已签候选重试始终沿用保存的原 CAS。
+
+## 4. 原始文件、严格解析与签名
+
+### 4.1 容器和角色
+
+YAML frontmatter＋可选 Markdown＋连续尾签块。首签前 payload 最多 4096 UTF-8 字节，整个尾签区最多 2048 字节。拒绝坏 UTF-8、非连续签块、重复字段／YAML 键、tag、锚点、别名和未知关系字段。
+
+| 文件 | Schema 和身份 |
+| --- | --- |
+| `agent.md` | 基础字段 `aid/name/type/version`；owner 与 ownership 同时出现／省略，含完整 statement；主签者和认证上传者均为 sub。human 不得声明 owner。 |
+| `owner.md` | 顶层恰为 `owner_aid/sub_aid/ownership`；路径 `owner_aid:/sub_aids/{sub_aid}/owner.md`；ownership 含 statement/action，仅 transfer_owner 另含 transfer。 |
+
+statement 恰含 `version/declaration_id/owner_aid/sub_aid/relation_version/declared_at`。action 为 `declare/release/transfer_owner`；transfer 恰含 `new_owner_aid/target_relation_version/expires_at`，绑定 `v+1`。文件角色取自资源上下文，不取自签名 TAG；不为 owner.md 伪造名片字段。
+
+### 4.2 数值词法不能在解析后丢失
+
+版本只接受原始十进制整数 token；拒绝 `1.0/1e0/+1/01`、数值 tag、字符串和布尔值。JSON 解析保留重复键与 number token，YAML 校验 scalar source，再转数值。
+
+`declared_at/expires_at/timestamp` 为 `1..9007199254740991` 的十进制正整数 Unix 秒；非法时间归 invalid。Python 排除 bool，Go 保留 JSON 数值词法；语言整数上限不能扩大协议范围。
+
+### 4.3 签名输入和摘要分别保存
+
+ECDSA P-256/SHA-256；签名为严格标准 Base64 的 ASN.1 DER，不能直接写 WebCrypto/P1363 的 `r||s`。首块签原始 payload，后块签之前的全部原始 prefix；不重排 YAML、换行或 Unicode。
+
+| 保存项 | 用途 |
+| --- | --- |
+| 完整原文 raw | 签验、原字节重传和附签。 |
+| 全文 SHA-256 | 包含全部签块的完整性与提交确认。 |
+| NS 原 ETag | 原样用于 If-Match，不能用本地摘要替代。 |
+
+agent／owner 默认 TAG 为 `AGENTMD-V2/OWNERSHIP-V2`，兼容标签以协议为准。普通两类文件主块禁止 signer_aid；附签必填，实体主块显式为实体 AID。已有附签全部验，数学失败不能降级成单签；末端删签不保证可检测。
+
+`AIDStore.sign/verify`、agent.md 和 owner.md 复用唯一通用签验 core，业务 Schema／当前授权在外层校验。TS/JS 公共签验为 `Promise<Result>`；文件输入显式 `inputType: 'file'`，document 成功后才可原地写回。参数见 [API 手册](06-API手册.md#通用-sign--verify)。
+
+## 5. 当前证书与吊销验证
+
+关系验证须核对精确 AID／证书 DER 指纹、P-256、可信链、当前有效性、`active_signing` 和可靠吊销状态；通用离线数学验签不承担这些事实。签名 timestamp 须在证书有效期内，未来偏差不超过 300 秒，也不能单独证明历史授权时间。
+
+[AuthFlow.resolveOwnershipCertificate](../../ts/src/auth.ts) 请求 authoritative PKI，并检查：
+
+| 权威头 | 要求 |
+| --- | --- |
+| X-AUN-Cert-Consistency／X-AUN-Cert-Lifecycle-State | authoritative／active_signing。 |
+| X-AUN-Cert-Fingerprint | 与请求和证书 DER 指纹精确匹配。 |
+| X-AUN-Cert-Observed-At | RFC3339；过去 ≤30 秒，未来 ≤5 秒。 |
+
+TS 当前使用直接 issuer 亲签的严格 OCSP DER：核对 CertID、ResponderID、签名和状态；ThisUpdate 过去 ≤30 秒，ProducedAt ≤90 秒，未来 ≤5 秒，NextUpdate 晚于当前及 ThisUpdate。网络等待后重读时钟并复核证书，整个验证窗口 ≤30 秒。未知状态、过期材料或缺权威证据为 unavailable；坏签名、吊销或非可签证书为 invalid。通用 CRL fallback 不是该 resolver 的替代证据。
+
+## 6. NS HTTP 与六态共识
+
+每个新 SDK NS GET/HEAD/PUT（含 fallback 和重试）携带 `X-AUN-Signature-Format: multi-v1`。fresh 再加 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache`；TS 使用 GET，禁止自动重定向。浏览器须能读取 CORS 暴露的关系头和 ETag。
+
+必验 `X-AUN-Ownership-Protocol: 2.1`、`X-AUN-Ownership-Version` 严格整数及 `X-AUN-Ownership-Lock: locked|unlocked`，存在时保留原 ETag。只有正确 NS 返回完整权威元数据的 404 才能解释为不存在；初始名片缺失仍不能开始绑定写入。
+
+```mermaid
+flowchart TD
+    A[开始计时；fresh NS 原文与元数据] --> B[严格解析，核对角色及当前证书]
+    B --> C[权威读取并验证规范 owner.md 或明确不存在]
+    C --> D{NS 元数据与文件材料冲突吗}
+    D -->|是，尚未重查| E[额外 fresh 重查一次并重验材料]
+    E --> D
+    D -->|仍冲突| U[unavailable；保留保护]
+    D -->|否| F[再次 fresh NS 核对原文、ETag、存在性、版本和锁]
+    F -->|变化或总计超过 30 秒| U
+    F -->|稳定| G[返回当前六态及权威摘要]
+    B -->|确定材料无效| I[invalid]
+```
+
+两类元数据冲突共用一次额外重查额度，不能省略最后稳定性复读。六态为 `consensus/released/unbound/single_sided/invalid/unavailable`，含义见 [应用指南 §7](Ownership2.1-SDK应用集成指南.md#7-任务完成与当前共识六态)。pending/unlocked 映射 single_sided，不授权；release 或权威缺失对应 released/v，清理后 unbound/0。转移授权过期不使旧关系失效。
+
+```ts
+const current = await files.checkConsensus(subAid);
+```
+
+提交使用 `submitAgentMdRaw`：已有文件仅带原 If-Match，首次创建仅带 If-None-Match=`*`；验证完整原件后 PUT，再 fresh 确认。428→unsupported_protocol，409/412→conflict，401/403→forbidden；不能去掉条件降级重试。
+
+旧客户端普通读写仍兼容。无 multi-v1 的多签读取投影为首块并使用该表示的 ETag；完整存储不变。Vary、304、Content-Length 和 CAS 映射必须区分表示，不能把投影摘要当完整存储摘要。
+
+## 7. Storage 权威读取、完整发布与权限
+
+固定 `owner_aid/bucket=default/object_key=sub_aids/{sub_aid}/owner.md/consistency=authoritative`。检查认证服务来源、命名空间、存在性和观察时间；存在时严格解码完整 content 并核对 SHA，前后权威观察 ≤30 秒且一致。普通读缓存、resolve 展示快照、超时或公开下载 404 均不能证明权威不存在。
+
+```mermaid
+sequenceDiagram
+    participant F as 文件层
+    participant L as 本地任务库
+    participant T as owner Storage
+    F->>T: 权威读取起始原文、存在性、SHA 和对象 version
+    F->>L: 保存起始证据、签名全文及原 expected_version
+    F->>T: 写前复读，精确核对起始原件
+    F->>T: create_upload_session，携带原 expected_version
+    T-->>F: session_id 与上传 URL
+    F->>T: HTTP PUT 完整文件
+    F->>T: complete_upload，同一 session_id／expected_version
+    T->>T: 校验大小、SHA、原版本后原子替换
+    F->>T: 权威复读确认完整原文
+```
+
+创建时 expected_version=`0`，更新时为起始权威对象的正安全整数 version；三阶段 Content-Type 一致，完成时公开可读。object_id/version 不参与只读共识，但发布／删除必须具备有效版本。起始 version 一经持久保存不得追随最新值重写旧任务。
+
+删除前 fresh 核对 NS 和本任务完整旧原件，再带最后读取且匹配原件的当前 version 条件删除；缺版本或 `-32009` 冲突即停止。只有本人可写删 owner.md，服务端须同时限制目录、移动、别名和批量入口。删除权威 owner 文件可导致释放，不是取消任务。
+
+这些复读不是跨服务一致快照，也不保证识别同内容 ABA 或完整文件回滚。
+
+## 8. 七个 Facade、事件与错误契约
+
+公有接口和事件见 [应用指南 §4–5](Ownership2.1-SDK应用集成指南.md#4-七个-facade-的参数角色与结果)。内部五步为 `declareOwneraid/declareSubaid/revokeOwneraid/revokeSubaid/transferOwneraid`，不创建任务、不发起审批。
+
+发起前匹配本端身份、发起方、操作、全部参与方和 base/target 版本：相同进行中意图复用 ID，同代际不同意图返回 conflict；终态不被迟到消息复活。任务 status 与共识 status 分开，事件在持久保存后发布。
+
+| 结果 | 任务语义 |
+| --- | --- |
+| 等审批／材料、unavailable、unsupported_protocol | pending，可保留原任务重试。 |
+| 原条件失效、目标／版本变化、授权过期 | stopped；停止前先核验目标是否已经提交。 |
+| 确定材料 invalid／明确拒绝 | error／rejected，不自动复活。 |
+| 目标与本任务证据精确匹配 | completed；通知和清理失败另留待办。 |
+| 本地存储或 revision CAS 失败 | persistence_unavailable，停止副作用。 |
+
+结果读取 code/reason/retryable；TS 异常的业务码为 `AUNError.stringCode`，数字 code 保留 RPC 语义。Storage Base64 传输封装损坏、同次权威元数据与正文摘要不一致归 unavailable；摘要匹配后确定非法的 UTF-8、字段或签名归 invalid。
+
+## 9. P2P 载荷与实际收件拦截
+
+控制类型固定 `aun.ownership.sdk.v1`；必含 operation_id、operation、action、sub/owner、base/target 版本，transfer 另含 new_owner。未知／缺失字段和非法整数词法拒绝；reason 仅用于 reject 或 operation.stopped。
+
+| 消息 | 方向 |
+| --- | --- |
+| bind.request／accept／reject | 绑定双方；owner-first 正常成功不要求 accept 往返。 |
+| transfer.request／ready | 原 owner → 新 owner、sub；accept/reject 反向回复。 |
+| owner.ready | sub-first 的 owner 或 transfer 的新 owner → sub。 |
+| relation.confirmed／sub.cleaned | bind/transfer 的 sub → 参与方；release 的 owner → sub，sub.cleaned 反向。 |
+| operation.stopped | 已关联任务的参与方 → 其他参与方。 |
+
+发送使用现有加密持久 `message.send`，不设 volatile TTL；来源只取消息层验证的 from_aid，不接受自发 P2P。ready／confirmed 只是提示，仍回源核对审批、固定上下文、授权和目标。
+
+```mermaid
+flowchart TD
+    A[push / pull / 重连 / 有序队列] --> B[解密，保留原 JSON 和已认证 from_aid]
+    B --> C{Ownership 控制类型吗}
+    C -->|否| D[普通应用消息]
+    C -->|是| E[检查词法、方向、固定任务上下文]
+    E -->|非法或不支持| F[消费控制消息，不作为聊天投递]
+    E -->|有效| G[按发送者、任务、action 去重，CAS 保存 inbox]
+    G -->|保存失败| H[抛错；保留原队列／游标，不 ACK]
+    G -->|保存成功| I[回源核验；失败保留已存待办]
+    I --> J[核验并持久保存后，才通知审批或推进]
+    J --> K[成功返回，delivery 才可移除消息、推进游标和 ACK]
+    F --> K
+```
+
+Client 拦截点在 `_publishAppEvent('message.received') → _handleOwnershipMessage → receive`；解密原文由 [decrypt.ts](../../ts/src/v2/e2ee/decrypt.ts) 保留。只给 handler 写 await 不够，[delivery.ts](../../ts/src/client/delivery.ts) 的所有实际投递路径都须等待它。
+
+```ts
+const consumed = await workflow.receive(authenticatedFromAid, decryptedJsonText);
+```
+
+`sub.cleaned` 在保存 inbox 前额外双读 NS，须稳定 unbound/0、空关系字段且 ETag 相同；不可确认则抛错保留投递，仍有关系则消费提示但不确认清理。
+
+## 10. 持久任务、审批与恢复
+
+### 10.1 存储契约
+
+TokenStore 提供 load/list/compareAndSwapOwnershipTask；不存在为 null，读取损坏与 CAS 失败为错误。新建 expectedRevision=null，更新比较原 revision 并递增。TS 使用每任务 SQLite 事务；进程内按 sub 串行，跨实例仍靠持久 CAS。
+
+| 记录 | 必须保存 |
+| --- | --- |
+| 上下文／审批 | 固定任务 ID、发起方、参与 AID、角色、base/target；本端决定及各 AID 审批。 |
+| 文件 | 起始双文件证据；本人已签全文、SHA、原 CAS；Stage 候选 raw/SHA/ETag；owner-first 提案原文／SHA。 |
+| 转移授权 | 首次验证的完整授权摘要和实际 expires_at，恢复不替换或延期。 |
+| inbox／outbox | 收件去重键；原回复、接收方、稳定 message_id 和发送进度。 |
+| 完成／清理 | 真实验收状态、版本、锁、NS ETag、双文件摘要、本人的签名原件与原条件；独立清理授权和进度。 |
+
+审批决定与回复原子保存后发送；完整签名文件和条件也先保存再发布。发件后清 outbox 失败允许原 message_id 重发，接收方幂等。已保存决定不可反转，同一 AID 的多角色合并，未决定的另一方仍可拒绝。
+
+### 10.2 恢复顺序与失败重试
+
+```mermaid
+flowchart TD
+    A[恢复原身份，读取并验证原任务] --> B{记录和完成证据完整吗}
+    B -->|否| P[persistence_unavailable；保留记录]
+    B -->|是| C[按 sub 串行：processInbox → flush → 确认／推进／清理]
+    C --> D{fresh 事实与本任务原件能确认目标吗}
+    D -->|是| E[保存真实 completed 证据，补有效通知和清理]
+    D -->|依赖不可用| W[pending；保留原任务]
+    D -->|未提交目标| F{原条件、审批及期限仍有效吗}
+    F -->|待审批| G[重新通知，等待明确决定]
+    F -->|是| H[复用原签名字节与 CAS，只补未完成步骤]
+    F -->|真实冲突／过期| I[stopped；不覆盖后续文件]
+```
+
+文件发布的持久化顺序示例，省略的前后校验仍按 §4–7 执行：
+
+```ts
+task.files.agent = saved;
+await task.persist();
+const published = await fileDeps.submitAgentMdRaw(
+  task.sub_aid, saved.raw, saved.condition,
+);
+```
+
+响应丢失先回源确认完整目标；仅同版本或某文件同 SHA 不足。已保存 published_etag 时必须匹配；尚未保存时仅在完整共识和本人原件匹配后补记。未提交且原条件有效才重传；不重签、不换 ETag、不延期。
+
+flush 每条通知前 fresh 核对对应原／目标关系，陈旧通知持久移除，未知时保留。completed 后只补有效通知或条件清理，不重跑关系提交；历史完成不要求历史证书今天仍可签。
+
+0.5.20／0.5.19 及更早任务保留原 operation、审批、字节和条件，不因缺后增字段一律重建。旧 expected_revision 无权威匹配证据时保持 unavailable，不能用当前 version 替代或从网络补造历史原件。reset 仅归档当前身份发起的未完成任务，保留远端文件，迟到消息不能复活。
+
+### 10.3 CAS 冲突分类与恢复边界
+
+| 条件层 | 结果与处理 |
+| --- | --- |
+| 本地 revision／浏览器 lease-fencing | persistence_unavailable；停止旧内存任务，后续恢复从存储重读。 |
+| NS 原 If-Match／If-None-Match | 412→conflict，语义冲突也可为409；fresh 核对全文、SHA、ETag、锁、版本和本地原证据。 |
+| Storage 原 expected_version | -32009→conflict；权威重读完整原件和版本，不刷新条件覆盖或删除。 |
+
+远端冲突只有完整目标及本任务原证据精确匹配才可确认完成；网络未知保留 pending。真实变化停止旧写入，按当前事实重新取得明确同意并发起合法操作，不自动 merge、重签或放宽 CAS。
+
+## 11. 三种流程与 self-owner
+
+| 流程 | SDK 内部步骤 |
+| --- | --- |
+| sub-first bind | 无锁／Stage 预检 → 保存 sub 同意 → declareOwneraid Stage → owner 审批 → declareSubaid → NS fresh 验收原候选。 |
+| owner-first bind | 无锁预检 → declareSubaid → request → sub 固定提案并同意 → declareOwneraid 直接提交。 |
+| release | revokeSubaid 发布同版本 release → fresh 确认 → 通知 sub → 授权清理 revokeOwneraid。 |
+| transfer | 收齐 sub／新 owner 同意 → transferOwneraid → 新 owner declareSubaid → sub declareOwneraid → fresh 确认和旧文件清理。 |
+
+### 11.1 EC CLI 创建 sub 后，由 human owner 确认绑定
+
+应用时序及 TS 调用见 [集成指南 §3](Ownership2.1-SDK应用集成指南.md#3-ec-cli-集成示例sub-发起human-owner-同意)。内部 Stage 分支必须保持：
+
+```mermaid
+flowchart LR
+    A[fresh 确认 Stage: 1] --> B[保存 sub 已同意的原件和原 CAS]
+    B --> C[条件 Stage PUT]
+    C --> D[响应确认 Stage: 1 和 pending]
+    D --> E[owner 发布匹配 declare]
+    E --> F[NS fresh CAS 清 pending，候选字节与 ETag 不变]
+    F --> G[locked；异步同步 Storage 名片副本]
+```
+
+Stage 能力由 fresh Check 响应的 `X-AUN-Ownership-Stage: 1` 确认，Stage PUT 成功也须回该头及 pending；缺失即停止。pending 不授权。owner-first 不用 Stage，审批前固定提案 raw/SHA，提交前仍须精确匹配，正常成功无 bind.accept／owner.ready 往返。拒绝只条件清理本任务未锁原件，已验收或被替换则停止。
+
+### 11.2 owner 释放与 sub 清理
+
+release 保持 v，owner 可在 sub 离线时凭 fresh released/v 完成。sub 已清字段时，只有本任务原件严格关联的真实 unbound/0 才能完成，不能补造 released 或历史条件；事件 relation_version 使用实际验收版本，任务 base/target 仍为 v。
+
+### 11.3 三方连续转移
+
+审批齐全后固定转移授权字节和 expires_at，再发布旧版本 transfer_owner、新 owner 的 v+1 declare、sub 的 v+1 名片。NS 直接切换，不经过 released；期限只限制新提交，恢复不延期。协议允许独立乱序发布，SDK 默认顺序用于恢复，NS 不维护审批任务。
+
+### 11.4 sub 的清理授权与 self-owner
+
+自动清理只引用本人明确 accept、含 sub 角色且本人已签完整声明完全匹配的原 bind/transfer 记录。收到释放通知时 pending 原任务也可提供授权；无消息时仅已完成历史任务的恢复触发。清理原件、SHA 和原 CAS 独立持久保存；缺授权发 action_required，release 不接受审批 Facade。
+
+self-owner 合并本端角色和决定，不发送自 P2P，仍分别签双文件并核验；human 禁止声明 owner，原／新 owner 相同不是有效转移。清理后重绑同一 owner，先清 sub 旧声明再发布新 declare。
+
+## 12. 普通／群名片、注册与兼容边界
+
+- 普通名片失败稿留本地；显式重试先检查保存的条件，再回源。缺条件不能因远端同字节而清待办；正文更新保留完整关系材料。重连不自动 PUT 普通 pending。
+- 实体 pending 保存完整多签原文、原 CAS、固定 owner 和实体证书代际，应用显式重试；转移／rekey／解散后停止旧待办。现代上传取消额外 V2 授权，旧入口按协议 §2.5 隔离兼容；专属 create/transfer checkpoint 恢复不变。
+- fresh 实体 GET 同时发 Check、no-cache、multi-v1，验证全部签块及当前实体代际，仍为 not_applicable。独立 AIDStore 的 Python／Go 实体上传需注入权威 owner resolver，TS／JS 默认经 fresh NS／PKI 核对。
+- 普通 agent 注册 owner 可选；有 owner 时固定 registration_intent ID，初始名片不写关系，连接后续跑绑定。注册成功不等于关系完成。
+- 新服务端保留旧认证、普通名片和隔离 legacy owner 操作；新 SDK 2.1 操作不兼容旧服务端。旧 proof 或 metadata 不当作 unbound 或当前授权，不能借升级清空锁。
+
+## 13. 跨语言 TDD 与有序验收
+
+先通过 [共同向量](../../tests/vectors/ownership_v21/vectors.json)，再按下表接线；TS 入口见 [conformance](../../ts/tests/conformance/ownership_v21.test.ts)、[文件测试](../../ts/tests/unit/ownership-v21.test.ts) 和 [Workflow 测试](../../ts/tests/unit/ownership-workflow.test.ts)。随机 ECDSA 不要求签名值一致，要求覆盖字节和跨端验签一致。
+
+| 顺序 | 必验边界 |
+| --- | --- |
+| 文件与密码 | 双角色、严格词法、字节限制、DER、多签、当前证书；invalid／unavailable 分类。 |
+| 权威适配 | NS 原条件／可靠不存在、Storage 完整发布／删除 CAS、fresh 稳定性和一次重查。 |
+| 持久编排／实际收件 | 审批／outbox 原子、消息去重、持久成功前不移除队列／推进游标／ACK。 |
+| 中断恢复 | 各提交前后丢响应、同意后断线、过期、后续关系、清理失败；原字节和原条件不变。 |
+| 网络与持久 | 单域 → E2E → cross-SDK → 双域；轮换角色，单独记录真实进程重启和服务数据库／副本证据。 |
+
+失败即停，修复失败项后从检查点续跑；已通过且不受影响的项不重跑。命令见 [测试指南](../aun测试运行指南.md)，历史验收范围见 [TDD 账本](Ownership2.1-TDD分阶段实施计划.md)。单元通过不代替真实浏览器、跨域或跨进程恢复验收。