@agentunion/fastaun 0.5.21 → 0.5.23

package/_packed_docs/sdk//345/207/255/350/257/201/344/270/216/347/273/204/347/273/207/346/234/215/345/212/241SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -1,211 +1,242 @@
 # 凭证与组织服务 SDK 开发与移植指南
 
-> 适用版本：四套 AUN SDK `0.5.19`，组织服务协议 `0.8`。
->
-> 本文面向实现其它语言 SDK、维护现有四端 SDK 或实现兼容 RPC 客户端的开发者。协议契约优先于任一参考实现；不能把 TypeScript、Python、JavaScript 或 Go 单端行为当作其它语言的隐含规范。
+面向 SDK 实现者，按“共同签验 → 请求绑定 → RPC → 持久状态 → 实体恢复”移植。协议为 Org `0.8`，SDK 为 `0.5.19` 基线及当前 `0.5.22` 工作区增量（未发布）。应用调用见 [集成指南](凭证与组织服务SDK应用集成指南.md)，字段以 [详细设计](../../../extensions/services/docs/org/0.8/17-凭证与组织服务详细设计.md) 为准，不以任一语言实现代替协议。
 
 ## 1. 实现层次和边界
 
-SDK 应保持以下分层：
+| 层次 | 职责／TS 参考 |
+| --- | --- |
+| 连接／RPC | 认证、Gateway service-plane、设备／slot、重连、token、外层签名；[rpc-pipeline.ts](../../ts/src/client/rpc-pipeline.ts)。 |
+| 协议 | canonical JSON、CAP、binding、回执、代表证明和完整 Verify；[org-protocol.ts](../../ts/src/org-protocol.ts)。 |
+| Facade | 参数和 method 映射，不复制组织服务状态机；[facades.ts](../../ts/src/facades.ts)。 |
+| 身份编排 | 组织实体身份、名片、rekey、checkpoint／恢复；[client.ts](../../ts/src/client.ts)。 |
 
-1. AUN 连接层负责认证、Gateway、设备/slot、JSON-RPC、重连和 access token。
-2. 协议层负责 canonical JSON、凭证/binding/receipt/representation 的结构校验、签名和完整 Verify。
-3. facade 层只做语言化命名、参数合并和 RPC method 映射；不要在 facade 中复制组织状态机。
-4. 高层身份编排层负责组织实体 AID、名片上传、转让 rekey、checkpoint 和恢复。
-
-Credential Service 与 Org Service 是独立服务，SDK 与服务之间只通过 AUN JSON-RPC、文件格式和环境约定协作。Credential 是业务服务：`credential.register/revoke/status/revocationList` 等业务 RPC 必须经 Gateway service-plane attach/dispatch，不得经 Kernel 调用；只有健康、状态诊断等控制面方法走 Kernel 控制面。`credential.status` 带凭证 CID 时始终是业务状态查询，走 service-plane。Credential facade 存在不代表 Credential 服务已部署；当前服务端明确保留但尚未实现的入口只有 `org.resource.create`、`org.task.create`、`org.host.add`、`org.workflow.create`，调用时返回业务码 `NOT_IMPLEMENTED`。其它同名资源、任务、主机和工作流方法不在当前 dispatcher 中，调用时按 JSON-RPC `Method not found` 处理。
+Credential／Org 业务经 Gateway service-plane，不经 Kernel；health／诊断走控制面。服务独立部署、独立数据库，不共享私钥或通过代码 import 耦合。
 
 ## 2. 共同密码学和 JSON 规则
 
 ### 2.1 两类 canonical JSON
 
-凭证协议对象（CAP、binding、receipt、representation、服务事件）使用协议 canonical JSON：对象键按 Unicode code point 排序，字符串 NFC，数字为最短十进制形式，拒绝孤立 surrogate；整数必须是有限且安全范围内的数学整数（绝对值不超过 `9007199254740991`）。签名输入是去除 `signature` 后的 UTF-8 bytes。
+| 输入 | 规范 |
+| --- | --- |
+| CAP／binding／receipt／representation／服务事件 | 键按 Unicode code point 排序，字符串 NFC，数字最短十进制；签名时去掉对象对应签名字段。 |
+| org 外层 client_signature 请求摘要 | 排序和数值规则相同，字符串保持原值，不 NFC。 |
 
-`org.*` 外层 `client_signature` 的请求摘要沿用现有 AUN 请求规则：对象键排序和数值规则相同，但字符串保持原值，不做 NFC；请求解析和签名前仍拒绝孤立 surrogate。两者不能共用一个“先 NFC 再签名”的简化实现。
+两者都拒绝孤立 surrogate、非有限或不安全数值。签名固定 ECDSA P-256/SHA-256，严格标准 Base64 的 ASN.1 DER；不能把 WebCrypto P1363 原样写入。
 
-签名算法固定为 ECDSA P-256/SHA-256，签名是 ASN.1 DER，外层是严格标准 Base64（必要时保留 `=`）。签名封套字段为：
+内部签名片段，unsigned 已按对象规则去除签名字段：
 
-```json
-{"cert_fingerprint":"sha256:<64位hex>","timestamp":1791321600,"signature":"<base64-der>"}
+```ts
+import { canonicalJson } from './org-protocol.js';
+const result = signer.sign(Buffer.from(canonicalJson(unsigned)));
+if (!result.ok) throw new Error(result.error.message);
+const envelope = { cert_fingerprint: signer.certFingerprint,
+  timestamp: now, signature: result.data.signature };
 ```
 
-`public_key_fingerprint` 可选；`algorithm`、`kid`、`value` 等旧字段必须拒绝。证书 resolver 应支持 PEM、DER bytes 和标准 Base64 DER，并验证证书指纹、Common Name/AID、P-256 曲线、公钥指纹和签名时间处于证书有效期。
+封套仅允许 cert_fingerprint、timestamp、signature 及可选 public_key_fingerprint；拒绝 algorithm/kid/value。resolver 支持 PEM／DER bytes／标准 Base64 DER，核对指纹、证书 AID、P-256 和签名时间。
 
 ### 2.2 摘要和随机数
 
-- 摘要格式统一为 `sha256:<64 位小写十六进制>`。
-- nonce 使用安全随机字节的 base64url；默认请求 nonce 为 32 字节。
-- `request_id` 是业务幂等键；Credential RPC 在同一 method、同一 request ID 下摘要不同时返回 `CREDENTIAL_IDEMPOTENCY_KEY_REUSE`。Org 的幂等冲突按对应 Org 契约返回 `IDEMPOTENCY_KEY_REUSE`。
-- `credential.register` 与补偿 `credential.revoke` 可以复用业务 request ID，但按 method 独立去重。
-- 不要把时间、nonce、CID 或摘要转成浮点；JavaScript/TypeScript 用 safe integer 检查，Go/Python 解析 JSON 时保留数学整数。
+摘要为 `sha256:<64位小写hex>`；nonce 为安全随机字节的 base64url，默认 32 字节。时间使用 Unix 秒及 `iat ≤ now < exp`，整数限制为 ±9007199254740991。
+
+幂等键为 method＋request_id，同键换参数摘要报 CREDENTIAL_IDEMPOTENCY_KEY_REUSE／Org IDEMPOTENCY_KEY_REUSE；register 与补偿 revoke 按 method 独立去重。JSON null／字段缺省和语言异步差异不得改变 wire。
 
 ## 3. AUN-CAP/1 实现契约
 
 ### 3.1 结构验证
 
-根/叶 CAP 至少含 `ver/cid/iat/iss/sub/aud/nbf/exp/cap/key_version/signature`；`delegation_depth`、`delegate`、`parent/proof_chain`、`security_level` 和 `ext` 按条件验证。根凭证的 `delegation_depth` 可省略并按 0 验证，若显式提供则必须为 0；子凭证必须显式提供直接父级有效深度加 1 的值，最大深度为 8。`security_level` 只允许 `low`、`medium`、`high`，缺省按 `medium` 处理；它是验证策略声明，不得被解释为可降低业务端最低安全策略或状态新鲜度要求。未知字段、空 AID、空受众、无约束能力、错误时间顺序、过深父链或错误签名结构必须 fail-closed。
-
-成员 CAP 的固定关系是：
-
-```text
-iss = binding.org_id
-sub = binding.member_aid
-aud 包含 binding.org_id
-cap = org / role.<binding.role> / binding.org_id
-ext.credential_type = member
-ext.membership_id/binding_version/membership_terms_hash 与 binding 相等
-ext.bound_to_membership = true
-delegate = false
-```
+CAP 必填 ver/cid/iat/iss/sub/aud/nbf/exp/cap/key_version/signature。拒绝未知字段、空身份／受众、非法时间、签名结构及超深父链。根深度缺省 0；子凭证显式为父深度＋1，最大 8；security_level 为 low/medium/high，缺省 medium，不能降低业务最低策略。
 
-`createMemberCredential`/`create_member_credential`/`CreateMemberCredential` 应拒绝对这些字段的冲突覆盖，且不允许成员 CAP 带 parent delegation。
+成员 CAP 固定为：iss=org_id、sub=member_aid、aud 包含 org_id，唯一能力为 org／role.<role>／org_id；ext 绑定 membership_id、binding_version、terms_hash，bound_to_membership=true、delegate=false，不允许 parent delegation。createMemberCredential 必须拒绝冲突覆盖。
 
 ### 3.2 验证级别
 
-实现至少提供两条明确 API：
-
-- `verifySignature`：结构、证书和 CAP 签名，可选时间/受众；不查询状态、不做授权。
-- `verify`：完整验证。
+```mermaid
+flowchart LR
+    A[结构、链、各层签名、时间和收窄] --> B[当前 CAP 及父链状态]
+    B --> C[实际能力和约束]
+    C --> D[实际请求 binding]
+    D --> E[成员双签和当前状态]
+    E --> F[代表证明、Ownership 和 actor 状态]
+    F --> G[重读时钟，复核全部有效窗口]
+    G -->|全部通过| H[授权结果]
+```
 
-完整 Verify 的最小顺序：
+```ts
+import { verifyCredential } from './org-protocol.js';
+const checked = verifyCredential(credential, verificationContext);
+```
 
-1. 验证内嵌或外置父链一致性、每一层签名、时间收窄、audience 收窄、能力收窄和 root issuer。
-2. 对每个父文档调用强 `resolveStatusProof`。受信 resolver 必须先验证 Credential 服务的签名、证书信任链和当前撤销状态，并确认 proof 中的查询 `request_id/nonce/target` 与实际请求及服务身份绑定；不能仅凭 proof 自报 `verified:true` 建立信任。SDK 再核对 `aun-credential-status/1`、CID、完整 CAP hash、active、asOf/proofExpiresAt、responder、request_id、nonce、target 和签名时间等字段。父 proof 缺失或畸形返回 `CREDENTIAL_STATUS_UNKNOWN`，CID/hash 明确不等返回 `CREDENTIAL_CHAIN_INVALID`。SDK 检查 proof 字段不等于自行建立 Credential 服务证书信任。
-3. 检查当前 CAP 的 `ns/action/resource/constraints`，包括 path、IP、regex、时间窗口、数值、allowed/denied 和 rate limit。
-4. 检查 `request_binding`：method、服务 target、params_hash、CID、request ID、nonce 和时间窗必须对应真实请求；通用及 admission binding 统一满足 `iat ≤ now < exp ≤ iat+300`。
-5. 成员 CAP 必须有完整当前 binding、双签和 `resolveMembershipStatus=true`；仅凭历史 binding 或 CAP active 不得放行。
-6. 代表调用必须验 representation proof，并通过受信 Ownership/actor 状态确认 actor 有权代表 target；actor 状态未知、封禁或 resolver 缺失拒绝。
+verifySignature 只做结构／证书／数学验签，可选时间和受众，不授权。verify 的 context 必须绑定实际 audience、subject、能力和 method/target/params/requestId/nonce/requestBinding。
 
-未显式指定 `now` 时，完成 resolver、成员与代表授权检查（包括异步等待）后重新读取当前时间，复核 CAP、能力时间约束、request binding、状态 proof、已用证书及 representation proof 的有效时间窗，不能沿用检查开始时的时间放行已过期材料。显式传入有效 `now`（Go 为非零 `Now`）时按该固定时间完成验证。
+有 parent 时，每个父文档必须取得强 resolveStatusProof；受信 resolver 先验服务签名、信任链／撤销及真实查询 request ID／nonce／target，SDK 再核对 aun-credential-status/1、CID／完整 CAP hash、active、responder 和证明窗口。缺失／畸形为 STATUS_UNKNOWN，明确 CID/hash 不符为 CHAIN_INVALID；不得降为字符串 active 或相信自报 verified。
 
-根凭证的旧字符串 status callback 可以保留兼容；有 parent 时不能降级为字符串 active。验证函数不得修改输入凭证或补写缺省签名字段。
+成员必须有当前 binding 双签及 resolveMembershipStatus=true；代表请求另验当前 Ownership 和 actor 状态。未指定 now 时，所有 resolver／异步等待后重读时钟，复核 CAP、证书、状态 proof、request binding 和代表证明；显式有效 now 按固定时间测试。校验不修改输入。
 
 ## 4. Membership binding、回执与请求绑定
 
 ### 4.1 Binding
 
-`aun-membership-binding/1` 的不可变 payload 去掉 `member_signature` 和 `org_signature` 后签名。成员和组织必须签同一份条款，且绑定 `membership_id`、`binding_version`、`terms_hash`、`request_id`、nonce 和时间窗。binding 不是能力凭证，状态由 Org Service 保存。
+成员和组织签同一不可变条款，签名 payload 去掉 member_signature／org_signature；绑定 membership_id、binding_version、terms_hash、request ID／nonce 和时间窗。binding 不是能力凭证，当前成员状态由 Org 保存。
 
-实现 `createMembershipBinding` 时允许传入 member signer、org signer 或两者；`signMembershipBinding` 只能让 member AID 签 member、组织 AID 签 org。申请和邀请的签名顺序不同，但 wire 字段相同。
+```ts
+import { createMembershipBinding, signMembershipBinding } from './org-protocol.js';
+const memberSigned = createMembershipBinding(bindingOptions, memberSigner);
+const bothSigned = signMembershipBinding(memberSigned, orgSigner, 'org');
+```
+
+申请先成员签，邀请先组织签；每个邀请目标独立 binding／nonce／CAP／登记授权，不能互换材料。
 
 ### 4.2 登记授权和回执
 
-颁发者登记时 `registrar_aid` 必须等于 `credential.iss`。转交服务使用 `registration_authorization`，签名覆盖完整 CAP hash、CID、原 request ID/nonce、Credential 服务 target、relay AID 和有效期；转交服务不能变成颁发者。
+```mermaid
+sequenceDiagram
+    participant I as issuer／Org SDK
+    participant O as Org 服务
+    participant C as Credential 服务
+    I->>O: 完整双签 binding、CAP 和登记授权
+    O->>C: register：原 CID、request ID、nonce 和请求绑定
+    C-->>O: 服务签名 registrationReceipt
+    O->>O: 核对服务、registrar=iss、CID／全文摘要、原请求和有效期
+    O->>O: 最终化成员及版本
+    O-->>I: 完整成员包
+```
+
+registration_authorization 由 issuer 签，覆盖完整 CAP hash、CID、原 request ID／nonce、Credential target、relay 和期限；转交服务不是 registrar。回执只是登记见证，不代替授权；公开验回执和服务最终化均按当前窗口严格检查。
 
-登记回执是 Credential Service 签名的见证，不是授权凭证。验收时核对 `credential_hash`（包含原 signature）、CID、registrar、service、status、registered_at/exp、request ID、nonce 和当前时间。回执缺失、重复使用、摘要不一致或服务状态未知均拒绝最终化。 已批准的续期受限跨期恢复仅在本地原期限内已持久化且已发送的同一操作中，保留原 CID/request_id/nonce、双签、登记授权和成员版本 CAS；如有原回执，私有恢复可按原登记时间验真作为历史来源；恢复仍须另取严格验签的新鲜 Credential status，绑定同一新 CAP 的 CID/完整摘要，并由当前成员确认同一关系及对应版本已生效，才保存已有结果，不重登记、不重签。无原回执的 generic 恢复须以新鲜签名 Credential status 及 registrationConfirmedAt 证明同一 CAP/完整摘要已提交，仅保存 issuer 本地 checkpoint，不导入 holder 账户、不发送 issued 结果消息、不重新 register；远端 holder 仍须原有效 registrationReceipt 完成交付。未提交、unknown、revoked 或材料不匹配均拒绝。公开 verifyRegistrationReceipt、服务最终化和 CAP 当前有效期不放宽；四 SDK 已完成定向实现与验证；具体定向与真实验收范围见 [审查报告 §7.14](../../../extensions/services/docs/org/0.8/凭证与组织服务及四SDK审查报告.md)，不代表全环境验收。
+受限跨期恢复只接受原期限内已持久且已发送的同一已批准操作，固定 CID／request ID／nonce、双签、登记授权和成员 CAS。原回执仅作私有历史来源，仍须新鲜签名状态绑定同一 CAP／全文摘要，并确认当前成员版本已生效；只记录既成结果，不重登记／重签。无原回执的 generic 恢复还须 registrationConfirmedAt，仅保存 issuer checkpoint，不导入 holder／发送 issued；holder 交付仍需有效原回执。unknown、revoked、未提交或不匹配拒绝，详见 [审查 §7.14](../../../extensions/services/docs/org/0.8/凭证与组织服务及四SDK审查报告.md)。
 
 ### 4.3 Org request binding
 
-`prepareOrganizationRequest` 等价实现必须：
+```mermaid
+flowchart LR
+    A[业务参数＋AAD＋授权包] --> B[去 request_binding、client_signature、下划线字段、representation_proof]
+    B --> C[业务摘要：request binding／代表证明]
+    C --> D[完整准备后的参数]
+    D --> E[仅去 client_signature 和下划线字段，重算外层摘要]
+    E --> F[RPC 管线生成 client_signature]
+```
+
+```ts
+const prepared = client.org.prepareRequest(
+  'org.member.get', params, orgServiceAid, signer,
+);
+const result = await client.org.member.get(prepared);
+```
 
-- 对所有 `org.*` 请求加入 `aad.org_id`，拒绝已有不一致 AAD；仅 `org.lifecycle.list`、`org.health`、`org.status` 允许 `org_id:null`。公开的 `org.lifecycle.get/list` 仍按服务端可见性规则处理，不因自动添加 AAD 而要求 CAP；`org.member.list` 等有组织目标的业务方法必须提供非空 `org_id`；
-- 计算 `request_binding.params_hash` 和 representation proof 所需的业务参数摘要时去除 `request_binding`、`client_signature`、所有 `_` 前缀字段和 `credentials.representation_proof`；保留其它 credentials 与 AAD；
-- `request_binding.params_hash` 与 representation proof 使用上述同一业务参数摘要；外层 `client_signature.params_hash` 在发送前对完整准备后的组织参数重新计算，保留 AAD、request binding 和授权包，只去除 `client_signature` 与 `_` 前缀字段，不得复用 `request_binding.params_hash`；
-- 首次 `org.member.join` 和 `org.member.inviteAccept` 一律使用 `membership_id` 专用 admission request binding，不伪造 `credential_cid`；本人和代表调用都必须提交目标成员的 `member_signature`，本人不要求已有 active 成员 CAP；仅代表另一个目标（`for != signer.aid`）时需要 admission representation proof 和当前 ownership/status 校验。本人直接 `inviteAccept` 复用邀请保存的组织签名、CAP 模板和登记授权，SDK 不重签或重造这些材料；
-- 对已有签名、binding、nonce 或外层重复签名做一致性比较，冲突直接报错。
+两层 params_hash 不可复用。所有 org.* 加 aad.org_id，不匹配即拒绝；只有 lifecycle.list／health／status 允许 null。外层签名覆盖完整 method、AID、timestamp 和外层摘要，服务端独立重算。
 
-外层 client signature 由 RPC pipeline 在发送 `org.*` 时生成，覆盖完整方法名、AID、时间戳和请求摘要。服务端仍须独立重算并验证，不能依赖 Gateway 的 verified 标志。
+首次 join／inviteAccept 使用 membership_id 专用 admission binding，复用原 request ID／nonce，不含 credential_cid，不要求已有 active CAP。本人／代表都须目标成员签名；仅 for≠signer.aid 加 admission representation proof 和当前 Ownership／actor 检查。inviteAccept 保留原组织签名、CAP 模板及登记授权；已有绑定／签名冲突不能重写。
 
 ### 4.4 Credential request binding
 
-`credential.register`、`credential.revoke`、`credential.status` 和 `credential.revocationList` 都必须携带 `request_binding`，至少绑定 `request_id`、nonce、target、完整 method、业务参数摘要、`iat/exp` 和 `credential_cid`。单凭证方法必须绑定对应非空 CID；`credential.revocationList` 是唯一例外，其 `request_binding.credential_cid` 固定为空字符串，摘要仍覆盖 issuer、cursor、limit、since_event_seq 等全部业务参数。不得把空 CID 例外扩展到其它方法。
+register／revoke／status／revocationList 均绑定真实 method、target、参数摘要、request ID／nonce、iat／exp 和 CID，满足 exp≤iat+300。仅 revocationList 的 CID 固定为空，摘要仍包含 issuer、cursor、limit、since_event_seq。
+
+内部 helper 示例；public Credential facade 不自动生成该绑定，也没有 credential.prepare：
+
+```ts
+import { buildRequestBinding } from './org-protocol.js';
+const requestBinding = buildRequestBinding(
+  method, credentialServiceAid, businessParams, cid, nonce, requestId, now, now + 300,
+);
+```
 
 ## 5. Facade 和 RPC 映射
 
 ### 5.1 四端公共能力
 
-| 能力 | Python | TypeScript | JavaScript | Go |
-|---|---|---|---|---|
-| Credential facade | `CredentialFacade` | `CredentialFacade` | `CredentialFacade` | `CredentialFacade` |
-| Org facade | `OrgFacade` | `OrgFacade` | `OrgFacade` | `OrgFacade` |
-| RPC 调用 | `await client.call` | `client.call` Promise | `client.call` Promise | `Call(ctx, method, params)` |
-| 协议层请求准备 helper | `prepare_org_request` | `prepareOrganizationRequest` | `prepareOrganizationRequest` | `PrepareOrganizationRequest` |
-| 完整验证 | `verify_credential` | `verifyCredential` | `verifyCredential` | `VerifyCredential` |
-| 状态 proof | `resolve_status_proof` | `resolveStatusProof` | 可返回 Promise | `ResolveStatusProof` |
+| 能力 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| facade | client.credential／org | client.credential／org | Credential()／Org() |
+| 请求准备 | org.prepare_request | org.prepareRequest | Org().PrepareRequest |
+| 完整验证 helper | verify_credential | verifyCredential | VerifyCredential |
 
-上表的“协议层请求准备 helper”不是 facade 的公开入口。公开 facade 方法分别为 Python `client.org.prepare_request`、TypeScript/JavaScript `client.org.prepareRequest`、Go `client.Org().PrepareRequest`；它们再调用表中的语言化 protocol helper。组织生命周期 facade 的创建方法也按各语言 API 命名，不应把统一概念名 `createOrg` 当作四端完全相同的公开方法名。
+协议 helper 和 facade 命名分开；创建高层入口分别为 org.lifecycle.create、client.createOrg、client.CreateOrg，不能将概念名当四端统一方法名。
 
 ### 5.2 当前方法集合
 
-Credential facade 映射：`credential.register`、`credential.revoke`、`credential.status`（`getStatus` 为别名）和 `credential.revocationList`，另有本地 `create/verifySignature/verify/verifyRegistrationReceipt`。 四 SDK 已在连接进入 READY 后扫描本地托管长期凭证及待恢复续期记录，并在在线期间每 60 秒重新扫描；断线、关闭及身份变化取消调度，异步扫描不得用旧身份提交。`aun-credential-renewal/1` 仍为当前实现性消息标识，自动续期状态机已完成四 SDK 定向实现与验证，不据此冻结跨版本消息契约；现有显式续期接口不变。
-
-Org facade 映射：
-
-- lifecycle：`create/get/list/update/suspend/resume/dissolve/transfer/transferAccept`；
-- member：`list/get/join/approveJoin/renewCredential/rejectJoin/add/invite/inviteAccept/inviteReject/leave/kick/offboard/freeze/unfreeze/ban/unban`；
-- credential：`getStatus/revocationList`；
-- audit：`query`；authz：`check`；health/status。
+Credential：register/revoke/status（getStatus 别名）/revocationList；本地 create/verifySignature/verify/verifyRegistrationReceipt/current。Org：lifecycle、member、credential、audit.query、authz.check；具体方法见 [RPC 手册](09-组织服务RPC手册.md)。
 
-Python/Go 另提供 `resource/task/host/workflow` 的保留 facade，分别对应 `org.resource.create`、`org.task.create`、`org.host.add`、`org.workflow.create`；当前服务 dispatcher 对这四个方法返回业务码 `NOT_IMPLEMENTED`。其它同名方法不在当前 dispatcher 中，调用时返回 JSON-RPC `Method not found`。`membership.reserve/get/commit/release` 是 Org 服务内部/受限接口，不能作为普通应用公共 API。
+保留的 resource.create／task.create／host.add／workflow.create 返回 NOT_IMPLEMENTED，其他未注册同类方法返回 Method not found。membership.reserve/get/commit/release 为内部受限接口，member.add 仅服务内部最终化使用。
 
 ### 5.3 异步约定
 
-Python RPC facade（如 `await client.call(...)`、`await client.org...`）是 async；Python 协议层本地 helper（如 `prepare_org_request`、`verify_credential`、`verify_credential_signature`）是同步函数。Node.js TypeScript 的协议 helper 同步；浏览器 JavaScript 中使用 WebCrypto 的 helper 异步返回 Promise。Go API 返回 `(value, error)`。异步差异只存在语言 API 层，不能改变 canonical bytes、字段缺省、错误码或 RPC envelope。
-
-## 6. 高层实体身份和转让编排
+Python RPC async、本地协议 helper 同步；Node TS 协议 helper 同步，浏览器 WebCrypto helper 返回 Promise，Go 返回 value/error。公共文件 AIDStore.sign/verify 的 TS／JS 接口均为 Promise<Result>；这些差异不能进入 wire。
 
-本节中的 `createOrg`、`completeOrgTransfer` 是高层能力的概念名称，不是四端统一的公开方法名：Python 使用 `client.org.lifecycle.create`、`client.org.lifecycle.transfer_accept`；TypeScript/JavaScript 使用 `client.createOrg`、`client.completeOrgTransfer`；Go 使用 `client.CreateOrg`、`client.CompleteOrgTransfer`。实现这些入口时必须持久化（包括自动生成组织 ID 的创建路径）：
+### 5.4 撤销同步与持久快照（0.5.22）
 
-- 组织实体私钥/证书和当前 owner；
-- 初始创建或转让的输入摘要、proposal、request ID/nonce、阶段 params；
-- transfer rekey 生成的新私钥 checkpoint；
-- 成功后的完整多签名片原文、原 CAS、固定 owner 与实体证书指纹。
-
-转让必须先 rekey 再 finalize：新 owner 生成新 P-256 key，rekey 返回新证书后导入，再以新证书重签双方角色材料并登记 CAP。finalize 使用独立持久 request ID；同 proposal、key、owner 和输入摘要恢复，材料改变返回 conflict。不要在 transfer 中复制旧组织私钥或跳过新证书指纹变化检查。
+```mermaid
+flowchart LR
+    A[推送／列表页] --> B[验证服务、目标、签名和时间窗]
+    B --> C[复核身份、连接和 worker 代次]
+    C --> D[读取当前 authority 快照，逐 CID 合并最大 event_seq]
+    D --> E[仅连续覆盖的列表页可推进分页位置]
+    E --> F[持久保存，再影响授权／通知应用]
+```
 
-解散高层入口以当前 signer 和调用方提供的当前成员 binding/CAP 调用既有 prepare helper，补齐 request ID、nonce、AAD 和 `request_binding`，核验已有请求绑定并保留原成员材料。组织解散成功后记录当前实体证书指纹为失效，并清理创建/转让 checkpoint、待上传名片和当前设备/slot 恢复状态；不删除磁盘私钥，也不追溯使已加载的 AID/signer 对象失效，后续 `AIDStore.load` 应拒绝该证书。实体 agent.md 与通用 Ownership 隔离：实体私钥主签并显式 signer_aid=org_id，当前 owner token 上传，可选当前 owner 附签且逐块全验；现代实体指纹严格匹配，Org 不开放旧实体上传，通用 Ownership facade 对 Org/Group 返回 not_applicable。取消实体额外 V2 授权及其过期窗口；pending 仅由应用显式重试，保留完整原文与原 CAS，并新鲜核对固定 owner／实体代际，转移、rekey 或解散后停止旧待办，不刷新条件或重签。专属 create/transfer 自身 checkpoint 恢复机制不变。复用唯一通用签验 core、显式文件输入、resolver 与 multi-v1 表示协商见 [Ownership 移植指南](Ownership2.1-SDK开发与移植指南.md#4-原始文件严格解析与签名) 和 [API 手册](06-API手册.md#通用-sign--verify)；本段不改变 CAP／成员 binding 签名机制。
+```ts
+import { verifyServiceEvent } from './org-protocol.js';
+const verifiedEvent = await verifyServiceEvent(eventName, payload, eventContext);
+```
 
-## 7. 服务端兼容实现要点
+四端使用既有 keystore/tokenstore 的 credential_revocations_v1 metadata（浏览器 IndexedDB），保存 version=1、authority 分区 revoked、since_event_seq、cursor、as_of、expires_at。单条推送不推进水位，旧页不覆盖新证据；本地未见 CID 不证明有效，完整 Verify 仍需新鲜状态 proof。
 
-Credential Service：
+兜底列表：连接后一小时首次，此后每小时，重连重新计时。长期凭证扫描：READY 后及在线每 60 秒；断线／关闭／身份变化取消旧代任务。续期成功立即保存完整 CAP、binding、terms、回执、服务版本和信息，供 credential.current 读取；只写当前成员账户，短期凭证保持 long_term=false。自动续期标识 aun-credential-renewal/1 不是跨版本冻结契约。
 
-- `credential.register` 只接受完整 CAP，验证父链、CID guard、nonce、登记授权并签回执；
-- `credential.revoke` 按 `(request_id, method)` 去重，支持父链级联和失败补偿封闭 CID；
-- `credential.status` 返回签名 status proof；`revocationList` 返回签名增量；
-- 服务身份或数据库不可用时返回状态未知，不签发临时服务签名。
+## 6. 高层实体身份和转让编排
 
-Org Service：
+```mermaid
+flowchart LR
+    A[校验 proposal、owner 和双方完整成员材料] --> B[生成新 P-256 私钥并持久保存 checkpoint]
+    B --> C[持久保存 rekey 参数后调用]
+    C --> D[导入匹配新公钥／指纹的证书]
+    D --> E[新实体签双方 binding／CAP，保存独立 finalize 请求]
+    E --> F[finalize：提交新成员包并撤旧 CAP]
+    F --> G[新实体主签、owner token 上传名片]
+    G --> H[保存 completed 结果，后续可精确重放]
+```
 
-- 对所有 `org.*` 独立验 client signature 和 AAD；再按方法及组织可见性执行授权。公开 `org.lifecycle.list/get` 的公开字段读取不要求 CAP/request binding，显式读取受保护字段、私有组织读取及 `org.member.list/get`、`org.credential.getStatus` 等受保护业务读取必须验证相应 CAP、membership binding、request binding、当前 actor/member 状态和权限；health/status 与 Name Service 受信读取按各自诊断/内部投影契约处理；
-- `member.add` 只允许 Org 内部最终化调用；应用不能绕过 join/approve/invite 流程；
-- 外部 Credential 操作不在 Org SQL 事务内，登记/吊销失败须持久化后台收尾；
-- 事件先独立验签，再以 `(responder,event_id,current_aid)` 去重；去重容量为最近 4096 项，不能承诺跨重启 exactly-once。
+```ts
+const result = await client.completeOrgTransfer(
+  originalTransferParams, { aidStore },
+);
+```
 
-两个服务通过现有 service-plane 注册和 Gateway 路由；服务 AID、数据库和日志目录隔离，不能通过代码 import 或共享表耦合。
+checkpoint 固定输入摘要、transfer ID、owner、proposal、原新私钥、公钥、阶段 request ID／nonce／params。恢复不复制旧组织私钥、不生成替代 key；输入或公钥变化报 conflict，缺原候选私钥报 persistence_unavailable。rekey／finalize 使用不同持久 request ID。
 
-## 8. 错误模型与兼容性
+0.5.22：Python 缺 key 保留 checkpoint 并拒绝；Go 导入前核对证书与 CA 结果指纹；TS／JS 保留 completed，精确同任务返回原结果，重连跳过完成态。不补造缺失的历史恢复材料。
 
-稳定业务错误码至少包括：`CREDENTIAL_INVALID`、`CREDENTIAL_SIGNATURE_INVALID`、`CREDENTIAL_STATUS_UNKNOWN`、`CREDENTIAL_REVOKED`、`CREDENTIAL_EXPIRED`、`CREDENTIAL_CHAIN_INVALID`、`CREDENTIAL_REQUEST_BINDING_INVALID`、`CREDENTIAL_CAPABILITY_DENIED`、`CREDENTIAL_IDEMPOTENCY_KEY_REUSE`、`MEMBERSHIP_STATE_INVALID`、`ROLE_ACCESS_DENIED`、`NOT_IMPLEMENTED`。
+组织名片实体主签、owner token 上传，可选当前 owner 附签且全验；现代指纹严格匹配，Org 不开放旧实体上传。完整多签原文、原 CAS、固定 owner／证书代际留待显式重试，重连不自动 PUT；转让／rekey／解散停止旧代待办。通用文件签验见 [Ownership 移植 §4](Ownership2.1-SDK开发与移植指南.md#4-原始文件严格解析与签名)，不改变 CAP／binding 算法。
 
-错误映射必须保留结构化业务码和 retryable 语义。网络/数据库/服务证书不可用可以重试；签名、摘要、字段、权限、状态和幂等 key 冲突不能盲重试。应用层不得根据错误文本推断授权结果。
+解散先以当前 binding／CAP 准备请求，服务确认 dissolved 后才标记实体证书失效，清创建／转让及名片待办和设备／slot 恢复状态；保留磁盘私钥，不追溯失效已加载 signer，后续 AIDStore.load 拒绝该证书。
 
-跨平台实现应避免：
+## 7. 服务端兼容实现要点
 
-- 依赖语言默认 JSON 序列化顺序或浮点解析；
-- 把 PEM 文本、DER bytes、Base64 DER 混成同一字符串比较；
-- 使用系统时区计算 Unix 时间或把 `exp` 当成包含端点；
-- 把 Python `None`、JS `undefined`、Go `nil` 无差别写入 wire；
-- 把异步 WebCrypto 的 Promise、Go error 或 Python exception 泄漏进 RPC 字段。
+| 服务 | 必须保持 |
+| --- | --- |
+| Credential | register 只收完整 CAP 并签回执；status／列表返回签名证明；revoke 从持久去重恢复原请求摘要、CID 和 revoked，冲突或损坏不当成功。 |
+| Org 授权 | 独立验 client signature／AAD；受保护读写验 CAP、binding、request binding 和当前 actor／member。公开 lifecycle 读取按可见性处理。 |
+| 跨服务收尾 | 外部登记／吊销不在 Org SQL 事务内，失败保留续跑；创建补偿遇幂等冲突停止自动补偿，槽位提交丢响应先复读原操作。 |
+| 转让／通知 | 新换钥前核对代际，以规范 SPKI DER Base64 调 CA；成员替换及新旧 owner 完整包通知同次持久保存，失败按组织轮转重试。 |
+| 事件／跨域 | 先验签，再按 responder/event_id/current_aid 去重（最近4096项，不承诺重启 exactly-once）；实体跨域重试用上传者域 token，向实体域提交原文件／CAS。 |
 
-## 9. 测试与验收
+以上需要配套服务部署；不能从 SDK 版本推断服务已具备。
 
-移植顺序建议固定为：
+## 8. 错误模型与兼容性
 
-1. 先通过共享 protocol vectors：canonical JSON、签名封套、CID/hash、binding、receipt、representation 和错误码。
-2. 再覆盖四类本地 helper：create、signature verify、full Verify、prepare request。
-3. 再覆盖 Credential register/status/revoke/revocationList 的 RPC transcript 和幂等/补偿。
-4. 再覆盖 Org create/join/approve/invite/inviteAccept/renew/offboard/transfer 两阶段和服务事件验签。
-5. 最后做单域、跨语言、跨域和故障恢复；真实 MySQL、多实例部署、Linux/macOS 仍需按服务 TDD 计划单独验收。
+保留结构化业务码及 retryable；不要解析错误文本。签名／链／摘要／binding／权限／成员状态／幂等键冲突不盲重试，服务／数据库／证书状态未知可等待但不授权。
 
-必须包含的负向向量：错误 issuer/sub/audience、父链 hash 不符、状态 proof 缺字段或过期、成员 binding/CID/version 不符、representation target 改写、AAD/params_hash 冲突、重复 nonce、幂等 key 换摘要、旧证书转让、rekey checkpoint 丢失和 `NOT_IMPLEMENTED` 方法。
+跨平台必须固定 Unicode／JSON 数值、PEM／DER／Base64 边界、UTC Unix 时间和 exp 开区间；不把 None／undefined／nil 混成相同字段，也不将 Promise／exception／error 写入 wire。
 
-代码参考：
+## 9. 测试与验收
 
-- TypeScript：`ts/src/org-protocol.ts`、`ts/src/facades.ts`；
-- 浏览器 JavaScript：`js/src/org-protocol.ts`、`js/src/facades.ts`；
-- Python：`python/src/aun_core/org_protocol.py`、`python/src/aun_core/org_facades.py`；
-- Go：`go/org_protocol.go`、`go/org_facades.go`；
-- 共同向量：`tests/vectors/org-0.8/protocol.json`；
-- 服务实现：`extensions/services/credential/go`、`extensions/services/org/go`。
+| 顺序 | 验收范围 |
+| --- | --- |
+| 共同向量 | [org-0.8/protocol.json](../../tests/vectors/org-0.8/protocol.json)：canonical bytes、DER、CID/hash、binding、receipt、representation 和错误码。 |
+| 本地 helper | 创建、签名预检、完整 Verify、请求准备；父链缺证明、错误 CID／版本、过期、代表目标及两层摘要冲突必须拒绝。 |
+| Credential RPC | register/status/revoke/列表，持久幂等、失败补偿、撤销推送／分页乱序、重启快照。 |
+| Org／恢复 | join/approve/invite/renew/offboard，rekey/finalize 断线、缺 key、完成重放、完整成员包、解散失效。 |
+| 网络 | 单域 → cross-SDK → 双域；真实数据库、多实例、浏览器和跨平台分别验收，失败即停并从检查点续跑。 |
 
-完整字段和阶段门禁见 [组织服务 0.8 详细设计](../../../extensions/services/docs/org/0.8/17-凭证与组织服务详细设计.md)、[TDD 实施计划](../../../extensions/services/docs/org/0.8/18-凭证与组织服务TDD实施计划.md) 和 [四 SDK 对齐变更清单](../../python/CHANGES_FOR_PARITY.md)。
+四端参考：TS／JS 的 src/org-protocol.ts、src/facades.ts；Python 的 aun_core/org_protocol.py、org_facades.py；Go 的 org_protocol.go、org_facades.go。版本专项与真实验收边界见 [四端对齐清单](../../python/CHANGES_FOR_PARITY.md)。

package/dist/agent-md.d.ts

@@ -20,6 +20,11 @@ export type AgentMdVerification = {
     reason?: string;
     ownership_status?: OwnershipVerificationStatus | 'not_applicable';
 };
+type AgentMdObservation = {
+    root: string;
+    etag: string;
+    version: number;
+};
 export interface AgentMdFrontmatter {
     aid?: string;
     name?: string;
@@ -114,7 +119,13 @@ export declare class AgentMdManager {
     private _loadRecord;
     loadRecord(aid: string): Record<string, unknown> | null;
     private _saveRecord;
-    saveRecord(aid: string, fields: Record<string, unknown>): Record<string, unknown>;
+    saveRecord(aid: string, fields: Record<string, unknown>, observation?: AgentMdObservation): Record<string, unknown>;
+    cacheOwnershipSnapshot(aid: string, snapshot: unknown, observation: {
+        root: string;
+        etag: string;
+        version: number;
+        content_hash: string;
+    }): boolean;
     private _clearConfirmedDraft;
     upload(content?: string | null, originalCondition?: OwnershipSavedFile['condition']): Promise<Record<string, unknown>>;
     readAgentMdFresh(aid: string): Promise<{
@@ -123,7 +134,9 @@ export declare class AgentMdManager {
         etag: string;
     }>;
     readOwnershipFresh(aid: string): Promise<OwnershipAgentObservation>;
-    submitOwnershipRaw(aid: string, raw: string, condition: OwnershipSavedFile['condition'], assertActive?: () => void): Promise<OwnershipAgentObservation>;
+    _readOwnershipQuery(aid: string): Promise<OwnershipAgentObservation>;
+    private _readOwnership;
+    submitOwnershipRaw(aid: string, raw: string, condition: OwnershipSavedFile['condition'], assertActive?: () => void, stage?: boolean): Promise<OwnershipAgentObservation>;
     private _ownershipRequest;
     uploadAs(targetAid: string, content: string, signer: AID): Promise<Record<string, unknown>>;
     private _pendingUpload;
@@ -181,3 +194,4 @@ export declare class AgentMdManager {
     private _writeRecordUnlocked;
     private _readRecordUnlocked;
 }
+export {};