@agentunion/fastaun 0.5.25 → 0.5.27

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/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -1,266 +1,973 @@
-# 凭证与组织服务 SDK 应用集成指南
-
-Org `0.8`，SDK `0.5.19` 基线及 `0.5.22` 工作区增量（未发布）。下文使用 Node TS；字段见 [Credential RPC](09-凭证服务RPC手册.md)／[Org RPC](09-组织服务RPC手册.md)，内部实现见 [移植指南](凭证与组织服务SDK开发与移植指南.md)。
-
-## 1. 先确认交付边界
-
-`client.credential` 处理凭证，`client.org` 处理组织／成员及请求准备。业务走 Gateway service-plane，Kernel 只做诊断；带 CID 的 credential.status 是业务查询。先确认服务已部署。
-
-保留的 org.resource.create／task.create／host.add／workflow.create 返回 NOT_IMPLEMENTED，其他未注册方法返回 Method not found。
-
-## 2. 运行前准备
-
-准备已连接客户端、本人 signer 和可信证书／状态 resolver；状态未知不授权。ownerSigner／memberSigner 属于当前会话，orgSigner 是 owner 本地组织实体身份；创建／转让使用固定持久 AIDStore。服务 target 使用 credential.{issuer}／org.{issuer}，已签材料固定原请求和成员。
-
-## 3. 凭证的应用流程
-
-### 3.1 创建并保留完整凭证
-
-```mermaid
-flowchart LR
-    A[issuer 创建并签署 CAP] --> B[登记完整凭证]
-    B --> C[验证服务登记回执]
-    C --> D[交付 holder]
-    D --> E[每次请求完整 Verify]
-    E -->|全部检查通过| F[执行业务]
-```
-
-```ts
-const credential = client.credential.create({
-  sub: holderAid, aud: [serviceAid], exp, key_version: issuerSigner.certFingerprint,
-  cap: [{ ns: 'files', action: 'read', resource: '/reports', constraints: [] }],
-}, issuerSigner);
-```
-
-sub 是实际 holder；保存完整签名对象。成员 CAP 用 org.member.createCredential(binding, orgSigner, options)，不手工拼装角色字段。
-
-### 3.2 选择正确的验证级别
-
-`verifySignature` 仅做结构、证书指纹和签名预检，可选时间／受众；执行授权使用完整 `verify`：
-
-```ts
-const checked = client.credential.verify(credential, {
-  ...trustedResolvers, ...actualRequest,
-  audience: serviceAid, subject: holderAid, rootIssuer: issuerAid,
-  ns: 'files', action: 'read', resource: '/reports',
-});
-```
-
-actualRequest 含真实 method/target/params/requestId/nonce/requestBinding。trustedResolvers 提供可信证书和当前状态；父链强 resolveStatusProof 须先验服务签名／信任／撤销及原查询，再由 SDK 核对 CID、全文 hash 和时间窗，不能返回裸 active。
-
-成员另传当前 membershipBinding／resolveMembershipStatus；代表调用另传 actor／for／representationProof 及当前 Ownership／actor 状态。任一步失败即停。
-
-### 3.3 登记、回执和吊销
-
-registrationParams 为持久保存的完整请求：原 request_id／nonce、registrar_aid、credential、request_binding；转交另含 issuer 登记授权。SDK 无 credential.prepare，按 [RPC 手册](09-凭证服务RPC手册.md#credentialregister) 准备。
-
-```ts
-import { isJsonObject } from '@agentunion/fastaun';
-const registered = await client.credential.register(registrationParams);
-if (!isJsonObject(registered)) throw new Error('登记响应无效');
-client.credential.verifyRegistrationReceipt(
-  registered.registrationReceipt, credential, registrationParams,
-  resolveCertificate, credentialServiceAid,
-);
-```
-
-回执须匹配服务／issuer、CID／全文 hash、原请求、状态和有效期；Org 验回执并最终化后成员才 active。
-
-```ts
-const result = await client.credential.revoke(revocationParams);
-```
-
-revocationParams 含原 CID、吊销授权／原因及本次绑定。仅明确 revoked 算完成；NOT_FOUND／unknown 不算。原 method／request ID／摘要幂等恢复，不能换 ID。所有 Credential 请求绑定方法、服务、参数、请求及时间窗；仅 revocationList 的 CID 为空。
-
-## 4. 组织成员流程
-
-### 4.1 组织创建
-
-```mermaid
-flowchart LR
-    A[owner 会话和持久 AIDStore] --> B[生成并保存组织实体身份]
-    B --> C[准备 owner binding、CAP 和登记授权]
-    C --> D[Org 登记 CAP、验回执并创建组织]
-    D --> E[实体主签，owner token 上传名片]
-```
-
-```ts
-const created = await ownerClient.createOrg(
-  { org_id: orgAid, name: '协作组织' }, { aidStore: ownerStore },
-);
-```
-
-组织名片实体主签、owner token 上传，含当前 owner／实体指纹，附签存在则全验。组织不走通用 Ownership 绑定，名片待办与创建结果分开。
-
-### 4.2 申请加入与邀请
-
-```mermaid
-sequenceDiagram
-    participant M as 成员 App
-    participant O as owner／管理员 App
-    participant G as Org 服务
-    participant C as Credential 服务
-    alt 成员申请
-        M->>G: join：成员签 binding
-        G-->>O: 待审批
-        O->>G: approveJoin：同条款组织签名、CAP、登记授权
-    else 组织邀请
-        O->>G: invite：每个目标独立 binding／CAP／登记授权
-        G-->>M: 原邀请材料
-        M->>G: inviteAccept：保留原材料，补目标成员签名
-    end
-    G->>C: 登记成员 CAP
-    C-->>G: 签名回执
-    G->>G: 验回执并最终化成员
-    G-->>M: active 与完整成员包
-```
-
-成员申请：
-
-```ts
-const joinParams = memberClient.org.prepareRequest('org.member.join', {
-  org_id: orgAid, member_type: 'human', requested_role: 'member', terms,
-}, orgServiceAid, memberSigner);
-const application = await memberClient.org.member.join(joinParams);
-```
-
-审批端的 applicationBinding／terms 取原申请响应 application 内的 membership_binding／terms；ownerCredentials 为审批者当前 binding／CAP：
-
-```ts
-const binding = ownerClient.org.member.signBinding(applicationBinding, orgSigner, 'org');
-const approval = ownerClient.org.prepareRequest('org.member.approveJoin', {
-  org_id: orgAid, terms, membership_binding: binding, credentials: ownerCredentials,
-}, orgServiceAid, ownerSigner, { orgSigner });
-await ownerClient.org.member.approveJoin(approval);
-```
-
-邀请端复用原 invitation 的组织、binding、terms、CAP 模板和登记授权：
-
-```ts
-const accepted = memberClient.org.prepareRequest(
-  'org.member.inviteAccept', invitation, orgServiceAid, memberSigner,
-);
-await memberClient.org.member.inviteAccept(accepted);
-```
-
-首次入组绑定 membership_id 和原 request ID／nonce，不带 CID／已有 CAP。本人和代表均须目标成员签名；for≠signer.aid 另验代表证明和当前 Ownership／actor 状态。
-
-### 4.3 查询、状态变更与续期
-
-```mermaid
-flowchart LR
-    A[同一成员关系，准备新 binding／CAP／登记授权] --> B[renewCredential：旧 CID＋当前版本 CAS]
-    B --> C[登记新 CAP 并验回执]
-    C -->|成功| D[提交新成员版本，再撤旧 CAP]
-    C -->|失败| E[仅补偿撤新 CAP]
-    D --> F[立即保存完整新成员包]
-```
-
-renewalMaterial 含旧 CID、expected_version、双签新 binding、terms、新 CAP／登记授权及当前调用授权：
-
-```ts
-const renewal = memberClient.org.prepareRequest(
-  'org.member.renewCredential', renewalMaterial, orgServiceAid, memberSigner,
-);
-await memberClient.org.member.renewCredential(renewal);
-const current = await memberClient.credential.current(memberCredential);
-```
-
-续期保持原成员关系，响应后立即持久完整成员包，credential.current 无需等事件。长期凭证 READY 后及在线每60秒扫描，显式短期凭证不自动续期。
-
-当前资格看签名 membership_status：banned／ended 拒绝，frozen 禁普通写，offboarding 仅收尾。离职按 leave/kick→offboard→ended→撤有权吊销的 CAP→清 active projection，失败续跑。
-
-## 5. 组织请求与跨设备代表
-
-### 5.1 统一请求准备
-
-```mermaid
-flowchart LR
-    A[业务参数＋本次授权包] --> B[prepareRequest：原 ID／nonce、AAD、request binding]
-    B --> C[必要时补代表证明]
-    C --> D[RPC 管线生成外层 client_signature]
-    D --> E[Gateway service-plane]
-    E --> F[服务独立重算签名、摘要和当前权限]
-```
-
-受保护读取也须准备请求，例如查询自己的成员状态：
-
-```ts
-const params = memberClient.org.prepareRequest('org.member.get', {
-  org_id: orgAid, member_aid: memberSigner.aid, credentials: memberCredentials,
-}, orgServiceAid, memberSigner);
-const member = await memberClient.org.member.get(params);
-```
-
-准备后原样发送，RPC 管线补 client_signature。受保护读取也需当前 binding／CAP；公开 lifecycle.get/list 按可见性处理。AAD 绑定 org_id，仅 lifecycle.list／health／status 可为 null。
-
-### 5.2 代表操作
-
-参数增加 for: holderAid，授权包仍属 holder。prepareRequest 绑定双方、方法、服务、摘要和时间窗；首次 admission 绑定 membership_id，其他代表绑定 CID。owner 不能替代目标成员签名。
-
-### 5.3 服务事件
-
-SDK 验服务、接收 AID、证书、签名和时间窗后去重；撤销同步如下：
-
-```mermaid
-flowchart LR
-    A[撤销推送／已签列表页] --> B[验签及身份／连接代次复核]
-    B --> C[按 authority、CID 保留最大 event_seq]
-    C --> D[持久保存快照]
-    D --> E[后续授权检查使用]
-```
-
-单条推送不推进分页，旧页不覆盖新证据，本地缺 CID 不证明有效。连接后一小时首次兜底拉列表，之后每小时；重连重新计时，与60秒凭证扫描独立。
-
-## 6. 所有权转让与实体材料
-
-```mermaid
-sequenceDiagram
-    participant O as 原 owner
-    participant N as 目标 owner SDK
-    participant G as Org 服务
-    participant CA as CA
-    O->>G: transfer：当前授权请求
-    G-->>N: transfer proposal
-    N->>N: 签接受材料，持久保存新 P-256 私钥与 checkpoint
-    N->>G: transferAccept stage=rekey
-    G->>CA: 复核代际并提交新公钥
-    CA-->>G: 新实体证书
-    G-->>N: pending_finalization 与新证书
-    N->>N: 导入证书，重签新旧 owner binding／CAP
-    N->>G: stage=finalize，独立持久 request ID
-    G->>G: 新 owner 生效，旧 owner 降 member，撤旧 CAP
-    N->>N: 新实体主签，owner token 上传名片
-```
-
-原 owner 准备并调用 org.lifecycle.transfer；目标验证 proposal，用 signTransferAcceptance 签接受字段。transferParams 保留这些字段、原 transfer_id、双方完整成员材料及授权包：
-
-```ts
-const transferred = await targetClient.completeOrgTransfer(
-  transferParams, { aidStore: targetStore },
-);
-```
-
-恢复沿用原 transfer ID、输入、阶段参数和私钥；缺 key 报 persistence_unavailable，材料变化报 conflict，TS／JS 精确完成态可重放。详见 [移植 §6](凭证与组织服务SDK开发与移植指南.md#6-高层实体身份和转让编排)。
-
-解散用 client.dissolveOrg(params, { aidStore })，提供当前 binding／CAP；确认 dissolved 后才失效本地证书并清恢复状态，保留磁盘私钥。名片失败稿保留完整多签、固定 owner／代际和原 CAS，仅显式重试，重连不 PUT；代际变化停止旧待办。
-
-## 7. 四端入口速查
-
-| 能力 | Python | TS／JS | Go |
-| --- | --- | --- | --- |
-| 业务入口 | client.credential／org | client.credential／org | client.Credential()／Org() |
-| 请求准备 | org.prepare_request | org.prepareRequest | Org().PrepareRequest |
-| 组织创建／转让 | org.lifecycle.create／transfer_accept | createOrg／completeOrgTransfer | CreateOrg／CompleteOrgTransfer |
-
-Node TS 协议 helper 同步，浏览器密码 helper 为 Promise；Python RPC async／协议 helper 同步，Go 返回 value/error。文件 AIDStore.sign/verify 的 TS／JS 均须 await。
-
-## 8. 错误与重试
-
-仅重试读取或原 method／request ID／摘要不变的幂等操作。签名／权限／binding／状态／幂等冲突不盲重试；未知暂缓副作用，创建补偿遇幂等冲突停自动补偿。
-
-跨期恢复只确认原期限内已持久且已发送的既成结果，不重登记／重签。无原回执时只保存 issuer 结果，holder 交付仍需原有效回执，边界见 [移植 §4.2](凭证与组织服务SDK开发与移植指南.md#42-登记授权和回执)。
-
-## 9. 验收清单
-
-覆盖完整 Verify、回执、双签入组、受保护读取、撤销乱序／重启、续期完整包、转让两阶段丢响应。运行见 [测试指南](../aun测试运行指南.md)，版本边界见 [四端对齐清单](../../python/CHANGES_FOR_PARITY.md)。
+# 凭证与组织服务 SDK 应用集成指南
+
+Org `0.8`；本文对齐当前工作区四 SDK（包元数据 `0.5.27`），不据此声明扩展已发布。§3为结构化凭证，§4为语义凭证，§5—§7为组织流程。下文使用 Node TS；字段见 [Credential RPC](09-凭证服务RPC手册.md)／[Org RPC](09-组织服务RPC手册.md)，内部实现见 [移植指南](凭证与组织服务SDK开发与移植指南.md)。
+
+| 模式 | 版本 | 授权验收 |
+| --- | --- | --- |
+| 结构化凭证 | `aun-cap/1` | 非空 cap，按能力、约束、来源链与当前状态确定性验收 |
+| 纯语义凭证 | `aun-cap/semantic-1` | cap=[]，正文、确认元数据与业务复核 |
+| 混合凭证 | `aun-cap/semantic-1` | 非空 cap 与正文限制取交集 |
+
+## 1. 先确认交付边界
+
+`client.credential` 处理凭证，`client.org` 处理组织／成员及请求准备。业务走 Gateway service-plane，Kernel 只做诊断；带 CID 的 credential.status 是业务查询。先确认服务已部署。
+
+保留的 org.resource.create／task.create／host.add／workflow.create 返回 NOT_IMPLEMENTED，其他未注册方法返回 Method not found。
+
+## 2. 运行前准备
+
+准备已连接客户端、本人 signer 和可信证书／状态 resolver；状态未知不授权。ownerSigner／memberSigner 属于当前会话，orgSigner 是 owner 本地组织实体身份；创建／转让使用固定持久 AIDStore。服务 target 使用 credential.{issuer}／org.{issuer}，已签材料固定原请求和成员。
+
+## 3. 结构化凭证接入
+
+### 3.1 非空约束与根凭证
+
+```mermaid
+flowchart LR
+    A[issuer 确定主体、受众、能力与约束] --> B[create 签署完整根 CAP]
+    B --> C[登记并验服务回执]
+    C --> D{使用方式}
+    D -->|直接使用| E[holder 每次请求完整 Verify]
+    D -->|允许委托| F[根 holder 签署收窄的子 CAP]
+    F --> G[子 CAP 登记，交付新 holder]
+    G --> E
+```
+
+本节使用同域 CN 客户端 issuerClient／delegateClient／holderClient／relayClient；对应 signer 由各自真实身份提供。app.save 保存材料，app.structured 封装[普通状态证明](凭证与组织服务SDK开发与移植指南.md#65-普通状态证明的可信适配)及[普通 CRL](凭证与组织服务SDK开发与移植指南.md#66-普通-crl-分页与原子持久)适配，认证会话闭包中的 queryActorAid 固定为 holderAid。
+
+```ts
+import { randomBytes as capRandomBytes, randomUUID as capRandomUUID } from 'node:crypto';
+import { isJsonObject, type JsonObject } from '@agentunion/fastaun';
+import { buildRequestBinding, canonicalJson as capCanonical,
+  digest as capDigest } from '../../ts/src/org-protocol.js';
+const credentialServiceAid = 'credential.agentid.cn';
+const capNow = Math.trunc(Date.now() / 1000);
+```
+
+org-protocol.js 的相对路径是仓库参考实现；npm 应用按[移植指南 §5.4](凭证与组织服务SDK开发与移植指南.md#54-credential-request-binding)在应用适配层封装同一绑定规则。
+
+```ts
+const rootCredential = issuerClient.credential.create({
+  sub: delegateSigner.aid, aud: [businessAid], delegate: true,
+  key_version: issuerSigner.certFingerprint,
+  cap: [{ ns: 'files', action: 'read', resource: '/reports', constraints: [
+    { type: 'max_value', field: 'rows', value: 100 },
+    { type: 'allowed_values', field: 'format', value: ['csv', 'json'] },
+  ] }],
+}, issuerSigner);
+await app.save('structured-root', rootCredential);
+```
+
+cap 限定命名空间／动作／资源；constraints 绑定实际请求字段。本例根凭证使用证书截止时间作为 exp，进入长期管理记录；显式短期 exp 按签署时给定期限使用。
+
+### 3.2 根到子：委托收窄
+
+```mermaid
+flowchart LR
+    A[根 sub 是本次子凭证签署者，根 delegate=true] --> B[固定 parent CID 与完整 proof_chain]
+    B --> C[受众、期限、能力、约束逐项收窄]
+    C --> D[create 签署子 CAP]
+    D --> E[完整 Verify 同时检查叶与全部父级]
+```
+
+```ts
+const credential = delegateClient.credential.create({
+  sub: holderAid, aud: [businessAid], parent: rootCredential.cid,
+  proof_chain: [rootCredential], delegate: false,
+  exp: Math.min(Number(rootCredential.exp), capNow + 1800),
+  key_version: delegateSigner.certFingerprint,
+  cap: [{ ns: 'files', action: 'read', resource: '/reports', constraints: [
+    { type: 'max_value', field: 'rows', value: 10 },
+    { type: 'allowed_values', field: 'format', value: ['csv'] },
+  ] }],
+}, delegateSigner);
+```
+
+| 项目 | 根 → 子 |
+| --- | --- |
+| 主体链 | 子 iss=根 sub；子 sub=最终 holder |
+| 能力与约束 | rows≤100 → rows≤10；csv／json → csv |
+| 时间与受众 | 子窗口位于父窗口内，子 aud 属于父 aud |
+| 来源链 | proof_chain 为直接 parent→root；最大深度 8 |
+| 成员 CAP | 用 org.member.createCredential 创建，保留其专用成员绑定流程 |
+
+### 3.3 普通请求绑定、登记与回执
+
+```mermaid
+sequenceDiagram
+    participant I as 签发者
+    participant R as 转交者
+    participant C as Credential 服务
+    I->>I: 固定原件、request_id、nonce 与请求参数
+    alt 签发者直接登记
+        I->>C: credential.register＋request_binding
+        C-->>I: 登记回执
+        I->>I: 验服务签名、CID／全文 hash、原请求及窗口
+    else 转交登记
+        I->>I: 签登记授权，绑定原件 hash／转交者／原请求
+        I->>R: 完整原件、授权与固定请求
+        R->>C: credential.register＋request_binding
+        C-->>R: 登记回执
+        R->>R: 验服务签名、CID／全文 hash、原请求及窗口
+    end
+```
+
+文内 credentialRequest 是应用封装，绑定前的 fields 已包含全部业务字段：
+
+```ts
+function credentialRequest(method: string, credentialCid: string, fields: JsonObject): JsonObject {
+  const now = Math.trunc(Date.now() / 1000);
+  const input = { ...fields, request_id: capRandomUUID(),
+    nonce: capRandomBytes(32).toString('base64url') };
+  return { ...input, request_binding: buildRequestBinding(method, credentialServiceAid,
+    input, credentialCid, input.nonce, input.request_id, now, now + 300) as JsonObject };
+}
+```
+
+根由原签发者直接登记：
+
+```ts
+const rootRegistration = credentialRequest('credential.register', String(rootCredential.cid), {
+  registrar_aid: issuerSigner.aid, credential: rootCredential,
+});
+await app.save('structured-root-registration', rootRegistration);
+const rootRegistered = await issuerClient.credential.register(rootRegistration);
+if (!isJsonObject(rootRegistered)) throw new Error('登记响应无效');
+issuerClient.credential.verifyRegistrationReceipt(rootRegistered.registrationReceipt,
+  rootCredential, rootRegistration, resolveCertificate, credentialServiceAid);
+```
+
+子凭证演示转交登记，registrar_aid 始终为子凭证签发者；先固定授权绑定的请求：
+
+```ts
+const registrationCore = { request_id: capRandomUUID(), nonce: capRandomBytes(32).toString('base64url'),
+  registrar_aid: delegateSigner.aid, credential };
+const authorizationCore = { ver: 'aun-credential-registration-authorization/1',
+  issuer_aid: delegateSigner.aid, credential_cid: credential.cid,
+  credential_hash: capDigest(credential), request_id: registrationCore.request_id,
+  nonce: registrationCore.nonce, target: credentialServiceAid, relay_aid: relaySigner.aid,
+  iat: capNow, exp: capNow + 300 };
+const authorizationSignature = delegateSigner.sign(Buffer.from(capCanonical(authorizationCore)));
+if (!authorizationSignature.ok) throw new Error('登记授权签名失败');
+```
+
+```ts
+const registrationFields = { ...registrationCore, registration_authorization: {
+  ...authorizationCore, signature: { cert_fingerprint: delegateSigner.certFingerprint,
+    timestamp: capNow, signature: authorizationSignature.data.signature } } };
+const registrationParams = { ...registrationFields, request_binding: buildRequestBinding(
+  'credential.register', credentialServiceAid, registrationFields, String(credential.cid),
+  registrationCore.nonce, registrationCore.request_id, capNow, capNow + 300) as JsonObject };
+await app.save('structured-child-registration', registrationParams);
+const childRegistered = await relayClient.credential.register(registrationParams);
+```
+
+```ts
+if (!isJsonObject(childRegistered)) throw new Error('登记响应无效');
+relayClient.credential.verifyRegistrationReceipt(childRegistered.registrationReceipt,
+  credential, registrationParams, resolveCertificate, credentialServiceAid);
+await app.save('structured-child-registration-result', childRegistered);
+await app.transport.sendEncrypted(holderAid, { credential, registrationReceipt: childRegistered.registrationReceipt });
+```
+
+resolveCertificate 预加载服务与原签署者的可信证书；证书信任／撤销按实际签署时点验证。原件、登记授权、request_id／nonce／绑定及回执一并保存。
+
+### 3.4 普通状态查询与强证明
+
+```mermaid
+flowchart LR
+    A[叶 CAP 与直接 parent 到 root] --> B[每个 CID 独立 status 查询绑定]
+    B --> C[验证服务证书信任、撤销与证明签名]
+    C --> D[核对查询者、ID／nonce、服务、CID／全文 hash 和窗口]
+    D --> E[缓存本次已验证完整 proof]
+    E --> F[resolveStatusProof 提供给完整 Verify]
+```
+
+```ts
+const checkedStatusProofs = new Map<string, Record<string, unknown>>();
+for (const document of [credential, rootCredential]) {
+  const statusInput = credentialRequest('credential.status', String(document.cid), {
+    credential_cid: document.cid,
+  });
+  await app.save('structured-status:' + String(document.cid), statusInput);
+  const rawStatus = await holderClient.credential.status(statusInput);
+  checkedStatusProofs.set(String(document.cid), await app.structured.verifyStatus(
+    rawStatus, document, statusInput, credentialServiceAid));
+}
+```
+
+verifyStatus 委托[verifyStructuredStatus](凭证与组织服务SDK开发与移植指南.md#65-普通状态证明的可信适配)，仅将已验真且 active 的完整 aun-credential-status/1 proof 放入 Map。proof.target 为真实查询者 holderAid，request_binding.target 为 Credential 服务。每次执行前重取或复核窗口内的证明。
+
+### 3.5 实际业务请求与完整 Verify
+
+```mermaid
+flowchart LR
+    A[认证收件取得 actor 与实际业务参数] --> B[固定 method／target／CID／ID／nonce／窗口]
+    B --> C[预加载可信证书与全部 status proof]
+    C --> D[完整 Verify：签名、父链、能力、约束、请求绑定]
+    D --> E[成员／代表场景附加当前资格]
+    E --> F[按原业务键幂等执行并保存结果]
+```
+
+```ts
+const operationMethod = 'reports.read';
+const operation = { report: 'monthly', rows: 5, format: 'csv',
+  request_id: capRandomUUID(), nonce: capRandomBytes(32).toString('base64url') };
+const operationNow = Math.trunc(Date.now() / 1000);
+const operationBinding = buildRequestBinding(operationMethod, businessAid,
+  operation, String(credential.cid), operation.nonce, operation.request_id,
+  operationNow, operationNow + 300);
+await app.save('structured-business-request', { ...operation, request_binding: operationBinding });
+```
+
+验收端从真实认证收件取得以下 operation、绑定与 holder 身份，预检与完整验收按用途选择：
+
+```ts
+const signatureReport = holderClient.credential.verifySignature(credential, resolveCertificate);
+const checked = holderClient.credential.verify(credential, {
+  audience: businessAid, subject: holderAid, rootIssuer: issuerSigner.aid,
+  ns: 'files', action: 'read', resource: '/reports',
+  method: operationMethod, target: businessAid, params: operation,
+  requestId: operation.request_id, nonce: operation.nonce, requestBinding: operationBinding,
+  resolveCertificate, resolveStatusProof: cid => checkedStatusProofs.get(cid),
+});
+```
+
+verifySignature 返回签名预检结果；业务执行使用完整 verify 的成功结果。约束字段从真实 params／units／clientIp 取得；rate_limit 使用应用事务限额端口 checkRateLimit。成员另传 membershipBinding／resolveMembershipStatus 与实际 orgSigner；代表调用另传 actor／for／representationProof 及当前 Ownership／actor 状态，见§5—§6。
+
+### 3.6 撤销、普通 CRL 分页与恢复
+
+```mermaid
+flowchart TD
+    A[issuer 固定 revoke 原请求] --> B[经认证 RPC 撤销，检查 CID 与 revoked]
+    B --> C[保存结果与撤销序号]
+    C --> D[按 authority、原 cursor／since_event_seq 拉 CRL]
+    D --> E[验服务签名、原查询、窗口及事件递增]
+    E --> F[同事务合并撤销最大序号与页面进度]
+    F -->|next_cursor 非空| D
+    F -->|next_cursor 为空| G[保存本轮完成进度]
+```
+
+子凭证由其签发者发起撤销；转交登记所用 relay 不自动取得任意撤销权：
+
+```ts
+const revocationParams = credentialRequest('credential.revoke', String(credential.cid), {
+  registrar_aid: delegateSigner.aid, credential_cid: credential.cid,
+  reason_code: 'grant_withdrawn', cascade: true,
+});
+await app.save('structured-revoke-input', revocationParams);
+const revokeResult = await delegateClient.credential.revoke(revocationParams);
+if (!isJsonObject(revokeResult) || revokeResult.credentialCid !== credential.cid
+  || revokeResult.status !== 'revoked') throw new Error('撤销结果无效');
+await app.save('structured-revoke-result', revokeResult);
+```
+
+```ts
+const crlProgress = await app.loadStructuredCrlProgress(credentialServiceAid);
+let structuredCursor = crlProgress.cursor || String(crlProgress.since_event_seq);
+```
+
+```ts
+do {
+  const crlInput = credentialRequest('credential.revocationList', '', { cursor: structuredCursor, limit: 100 });
+  await app.save('structured-crl:' + structuredCursor, crlInput);
+  const rawPage = await holderClient.credential.revocationList(crlInput);
+  const page = await app.structured.verifyCrl(rawPage, crlInput, credentialServiceAid);
+  await app.commitStructuredCrlPage(credentialServiceAid, page);
+  structuredCursor = page.next_cursor;
+} while (structuredCursor !== '');
+```
+
+普通 CRL 结束游标为 `''`。verifyCrl 委托[verifyStructuredCrl](凭证与组织服务SDK开发与移植指南.md#66-普通-crl-分页与原子持久)，核对 responder、target、request_id／nonce、issuer 过滤、证明窗口及事件序号；commitStructuredCrlPage 按 authority／CID 合并最大 event_seq，并原子保存游标。单条推送保留较新撤销证据，分页进度由完整已验页面推进。
+
+```mermaid
+flowchart LR
+    A[恢复同一 AID 与持久 store] --> B[current 读取已管理凭证及续期 successor]
+    B --> C[加载原请求、原件、授权、回执与业务结果]
+    C --> D[重取全部状态 proof，按原请求复核结果]
+    D --> E[原幂等键续跑，保存本阶段结果]
+```
+
+以下示例用于原绑定与登记授权仍在有效窗口内的丢响应重试：
+
+```ts
+const managedRoot = await issuerClient.credential.current(rootCredential);
+if (managedRoot?.credential) await app.save('structured-current-root', managedRoot.credential);
+const savedRegistration = await app.loadStructuredInput('structured-child-registration');
+const recoveredRegistration = await relayClient.credential.register(savedRegistration);
+if (!isJsonObject(recoveredRegistration)) throw new Error('登记响应无效');
+relayClient.credential.verifyRegistrationReceipt(recoveredRegistration.registrationReceipt,
+  credential, savedRegistration, resolveCertificate, credentialServiceAid);
+```
+
+current 返回当前身份已管理的记录；显式短期 CAP 沿保存的原件使用。跨期恢复按原回执与 SDK 提交检查点确认既成结果，见§9与[移植指南 §5.2](凭证与组织服务SDK开发与移植指南.md#52-登记授权和回执)。
+
+## 4. 语义凭证接入
+
+### 4.1 材料与公共准备
+
+各角色使用自己的已连接 client。语义入口平铺在 client.credential，版本为 aun-cap/semantic-1；Node TS 为下文基准。字段见[正式规范](../../../extensions/services/docs/org/0.8/语义凭证扩展规范.md)及[RPC 手册](09-凭证服务RPC手册.md#语义凭证公共约定)。
+
+| 依赖 | 来源与职责 |
+| --- | --- |
+| issuerSigner／confirmerSigner | 签发者 A／确认者 K 的真实身份及授权依据 |
+| authority／policy／trust | 登记管理权限、固定版本策略、证书解析和信任校验 |
+| app.* | 应用端口：持久保存、认证通道、正文材料、模型、后置复核、事务账本与执行器 |
+
+```ts
+import { randomBytes, randomUUID } from 'node:crypto';
+import { semanticProtocol as sp } from '@agentunion/fastaun';
+const options = { serviceAid: 'credential.agentid.cn', verificationContext: trust };
+const management = (credential_cid: string) => ({
+  request_id: randomUUID(), nonce: randomBytes(32).toString('base64url'),
+  credential_cid, authority,
+});
+```
+
+管理写操作在首次调用前持久保存完整 input；幂等重试读取原 input。facade 按当前 Unix 秒补管理绑定。SignedJsonBytes={bytes_base64} 保留签署后的严格 UTF-8 JSON 原字节，使用标准带 padding Base64；EvidenceRef 使用独立包装。
+
+### 4.2 签发、确认与登记（E02—E05、E18）
+
+```mermaid
+sequenceDiagram
+    participant A as 签发者 A
+    participant K as 确认者 K
+    participant R as 登记权威 R
+    A->>A: signCredential：正文与显式上限
+    A->>K: 原件及确认权依据
+    K->>K: signMetadata：确定 iss/sub/aud/期限/次数
+    K->>R: register：原件、metadata、来源链、管理权限
+    R-->>K: CID、original_hash、逐 aud 修订与回执
+    K->>K: 持久保存原字节与登记结果
+```
+
+textGrant 的正文明确授权对象、业务操作、期限和次数：
+
+```ts
+const now = Math.trunc(Date.now() / 1000);
+const textGrant = {
+  ver: 'aun-cap/semantic-1', cid, cap: [],
+  iss: issuerSigner.aid, sub: holderAid, aud: [businessAid],
+  nbf: now, exp: now + 3600, delegate: false,
+  authorization: { kind: 'text', text: grantText },
+} satisfies Omit<sp.SemanticCredential, 'signature'>;
+const original = await client.credential.signCredential(textGrant, issuerSigner);
+```
+
+累计额度绑定来源链根原件；本例为根凭证的一次使用：
+
+```ts
+const usage = {
+  grant_key: sp.digest(['AUN-CAP-GRANT-v1', cid, sp.digest(sp.decodeSignedJson(original))]),
+  epoch: 1, audiences: [businessAid],
+  ledger: { scope: 'global', authority: ledgerAid },
+  limits: [{ id: 'reads', metric: 'count', unit: 'request', limit: '1' }],
+} satisfies sp.UsageContract;
+```
+
+```ts
+const metadata = await client.credential.signMetadata({
+  original_hash: sp.digest(sp.decodeSignedJson(original)), version: 'm1',
+  confirmed_at: now, iss: issuerSigner.aid, sub: holderAid, aud: [businessAid],
+  nbf: now, exp: now + 3600, use_limit: 1, usage, delegate: false, policy,
+  confirmation: { authority: confirmerSigner.aid,
+    authorization: confirmationPolicy, audiences: [businessAid] },
+}, confirmerSigner);
+```
+
+```ts
+const registrationInput = { ...management(cid), original, metadata: [metadata],
+  lineage_evidence: [] } satisfies sp.SemanticFacadeInput<sp.SemanticRegisterParams>;
+await app.save('registration-input', registrationInput);
+const registered = await client.credential.register(registrationInput, options);
+await app.save('registered', registered);
+```
+
+| 分支 | 签发与确认材料 |
+| --- | --- |
+| 纯语义 | cap=[]，metadata 确定授权字段 |
+| 混合 | cap 非空；验收取结构化范围与正文的交集 |
+| 明确无限期／无限次 | 正文明确，对应原件上限省略；metadata 使用 exp=null／use_limit=null |
+| 待补确认 | 返回具体补充项，有权方补签后重新登记／出示 |
+| 派生凭证 | lineage_evidence 保存 root→直接 parent 的完整材料 |
+
+```ts
+const mixedOriginal = await client.credential.signCredential({
+  ...textGrant, cid: mixedCid, cap: structuredCaps,
+}, issuerSigner);
+```
+
+### 4.3 消息正文与证据（E06—E11、E15、E32）
+
+```mermaid
+flowchart TD
+    A[认证通道取得原始 envelope 与收件记录] --> B[archiveMessage 保全原字节]
+    B --> C{证据交付方式}
+    C -->|inline| D[使用 archive.envelope]
+    C -->|aun_ref| E[按 ACL 保存对象与版本，生成引用]
+    D --> F[签署 message_ref，固定 signed_core_hash 与会话]
+    E --> F
+    F --> G[验发送者、原收件资格、解密与正文]
+    G -->|材料齐备| H[VerifiedBody 进入业务判断]
+    G -->|待补| I[补原材料，或有权方另签自足 text]
+```
+
+```ts
+const archive = await client.credential.archiveMessage(rawEnvelope, received);
+await app.archive.put(archiveLocator, archive.envelope_bytes);
+const envelopeRef = await client.credential.createEvidenceRef(
+  archive.envelope_bytes, 'aun-e2ee-v2-envelope-raw/1', archiveLocator,
+);
+const referencedOriginal = await client.credential.signCredential({
+  ...messageGrant, authorization: { kind: 'message_ref',
+    message: { ...messageRef, envelope: envelopeRef } },
+}, issuerSigner);
+```
+
+```ts
+const inlineRef = archive.envelope;
+const resolved = await client.credential.resolveEvidence(envelopeRef, archiveResolvers);
+const body = await client.credential.verifyMessageBody(referencedOriginal, messageContext);
+```
+
+| 分支 | 固定材料 |
+| --- | --- |
+| 自足 text＋消息溯源 | authorization.evidence 保留消息证据；正文使用独立 text 签名 |
+| P2P | conversation={kind:'p2p',to}、原接收 AID／设备／历史解密材料 |
+| 群消息 | conversation={kind:'group',group_id,epoch,state_commitment}；完整收件集合或单行 Merkle 证明 |
+| 上下文／附件 | message.context 使用消息原件；attachments 使用 aun-evidence-bytes/1 |
+| 长期归档 | 原字节、对象版本、ACL、历史证书、解密能力及 retain_until |
+
+messageContext 提供可信证书、发送者历史身份与原收件密钥；received 取实际认证收件记录。签署 messageRef 的 signed_core_hash 算法见[移植指南 §4.5](凭证与组织服务SDK开发与移植指南.md#45-消息证据适配)。
+
+### 4.4 来源链、交付与业务请求（E12—E16、E26）
+
+```mermaid
+flowchart LR
+    A[get 当前原件、metadata 与回执] --> B[逐层取得 bounded 状态快照]
+    B --> C[buildPackage：root 到 leaf]
+    C --> D[AUN 加密交付 holder]
+    D --> E[buildRequest 固定业务 hash]
+    E --> F[逐层查询 online 状态并替换快照]
+    F --> G[认证通道向业务方出示]
+```
+
+单层当前材料的准备；多跳按 root→leaf 重复：
+
+```ts
+const current = await client.credential.get({ ...management(cid), audience: businessAid }, options);
+if (current.kind === 'revision' && current.head.state === 'current') {
+  const status = await client.credential.status({
+    ...management(cid), audience: businessAid, expected_revision: current.revision,
+    policy: { mode: 'bounded', max_staleness_seconds: 60 },
+  }, options);
+  await app.saveEntry({ credential: sp.decodeSignedJson(current.original) as sp.SemanticCredential,
+    metadata: sp.decodeSignedJson(current.metadata) as sp.RegistrationMetadata,
+    registration_receipt: current.registration_receipt, status });
+}
+```
+
+```ts
+const grant = await client.credential.buildPackage(lineage);
+await app.transport.sendEncrypted(holderAid, grant);
+const request = await client.credential.buildRequest({
+  request_id: randomUUID(), nonce: randomBytes(32).toString('base64url'),
+  actor: presenterAid, sub: holderAid, target: businessAid, aud: businessAid,
+  ns: 'files', action: 'read', resource: '/reports', params: { report: reportId },
+  expires_at: Math.trunc(Date.now() / 1000) + 300, grant,
+});
+await app.save('business-request', request);
+```
+
+| 来源链分支 | 验收配置 |
+| --- | --- |
+| 纯语义／混合多跳 | 逐跳身份、delegate、深度≤8、期限、aud、能力和全部适用正文 |
+| 旧根→语义叶 | packageContext.legacyVerifier 使用普通凭证完整验证及原权威强状态 |
+| 父级 message_ref | app.messageContext 为每层提供原收件材料；全部正文进入 DecisionInput |
+| 代表调用 | actor 为真实发送者，sub 为叶 holder；verifyRepresentation 核验当前代表依据 |
+
+### 4.5 online／bounded 与状态刷新（E19—E22、E26）
+
+```mermaid
+flowchart TD
+    A[固定业务 request_hash] --> B{状态策略}
+    B -->|online| C[独立查询 nonce，记录单调起点]
+    C --> D[status 绑定业务 hash，查询到确认小于 30 秒]
+    B -->|bounded| E[指定 1 到 300 秒 TTL，按本地观察计时]
+    D --> F[验服务、修订、state_seq 与绝对窗口]
+    E --> F
+    F --> G[替换同修订 status，保持业务 hash]
+    G --> H[业务执行前再次复核]
+```
+
+online 示例展示一层，逐层分别保存 query 与单调起点：
+
+```ts
+const query = { request_hash: request.request_binding.request_hash,
+  nonce: randomBytes(32).toString('base64url') };
+const began = performance.now();
+const online = await client.credential.status({ ...management(cid),
+  audience: request.aud, expected_revision: revision, policy: { mode: 'online' }, query,
+}, options);
+await client.credential.verifyStatus(online, { ...trust, expectedServiceAid: options.serviceAid,
+  policy: { mode: 'online' }, query, elapsedSeconds: (performance.now() - began) / 1000 });
+```
+
+```ts
+const bounded = await client.credential.status({ ...management(cid),
+  audience: request.aud, expected_revision: revision,
+  policy: { mode: 'bounded', max_staleness_seconds: 60 },
+}, options);
+```
+
+```ts
+const refreshed = structuredClone(request);
+const leaf = refreshed.grant.lineage.at(-1)!;
+if ('metadata' in leaf) leaf.status = online;
+const unchangedHash = await client.credential.requestHash(refreshed);
+await app.transport.submit(businessAid, refreshed);
+```
+
+管理 nonce、业务 nonce、online 查询 nonce 分别生成。bounded 本地耗时须小于 TTL；两种策略均复核绝对窗口及最大已观察序号。刷新仅替换同修订状态；正文／metadata／回执／操作／期限变更使用新业务请求。角色变化后仍按原授权条件验收，显式撤销按当前状态策略生效。
+
+### 4.6 业务验收与模型三态（E16、E18、E23—E25、E34）
+
+```mermaid
+flowchart TD
+    A[真实认证 actor 与 service] --> B[verifyRequest 与 verifyPackage]
+    B --> C[签发权、确认权、历史 policy、前置名单与约束]
+    C --> D[逐层验真正文，取得可信事实]
+    D --> E[buildDecisionInput，模型三态判断]
+    E -->|deny| F[保存拒绝结果]
+    E -->|indeterminate／超时／异常| G[保存待补项]
+    E -->|allow| H[后置复核与当前状态确认]
+    H -->|事实／策略变化| C
+    H -->|修订／回执变化| J[重新取材料与 buildRequest]
+    J --> A
+    H -->|通过| I[事务预留与幂等执行]
+```
+
+```ts
+const authentication = await app.transport.authenticationFor(request);
+const bindingReport = await client.credential.verifyRequest(request, authentication, {
+  representedActor: app.verifyRepresentation,
+});
+const packageReport = await client.credential.verifyPackage(request.grant, packageContext);
+await app.verifyAuthorities(request);
+await app.checkStructuredCapabilities(request);
+await app.precheck(request, facts);
+```
+
+```ts
+const bodies = [];
+for (const entry of request.grant.lineage) {
+  if ('metadata' in entry) bodies.push(await client.credential.verifyMessageBody(
+    entry.credential, await app.messageContext(entry),
+  ));
+}
+const input = await client.credential.buildDecisionInput(request, bodies, facts, policy);
+```
+
+```ts
+const decision = await app.evaluate(input);
+await app.saveDecision(input, decision);
+if (decision.verdict === 'allow') {
+  await app.postcheck(input, decision);
+  await app.refreshAndVerify(request);
+  await app.executeOnceWithUsage(request, decision);
+}
+```
+
+app.evaluate 将模型超时／无效输出归为 indeterminate；app.precheck 完成前置名单与本次确认准入，app.postcheck 复核确认与业务后置条件。packageContext 提供原签署者、各层登记权威、旧层验证器、状态 query 和真实单调耗时；checked／required 分别用于记录已完成检查与应用待完成职责。缓存绑定请求、正文、facts、policy、修订及状态版本。
+
+### 4.7 受众修订、历史读取与撤销（E17—E18、E21—E22）
+
+```mermaid
+flowchart LR
+    A[get 当前 head] --> B[确认新 metadata]
+    B --> C[revise 批量 CAS]
+    C -->|提交| D[保存新 revision 与 state_seq]
+    C -->|冲突| A
+    D --> E{变更范围}
+    E -->|指定 aud| F[withdraw 或按最后 head 重加]
+    E -->|整个 CID| G[revoke，持久保存撤销结果]
+```
+
+```ts
+const revisionInput = { ...management(cid), kind: 'metadata' as const,
+  change: { expected: [{ audience: businessAid, revision }], metadata: [newMetadata] },
+};
+await app.save('revision-input', revisionInput);
+const revised = await client.credential.revise(revisionInput, options);
+```
+
+| 变更 | change |
+| --- | --- |
+| 替换／批量替换 | expected=[当前 AudienceRevision]，metadata=[新签 metadata] |
+| 新增 aud | expected_absent=[aud]，expected=[]，metadata=[新签 metadata] |
+| 撤下 aud | expected=[当前 AudienceRevision]，withdraw=[aud]，metadata=[] |
+| 重加 aud | expected_withdrawn=[aud、last_revision、state_seq]，expected=[]，metadata=[新签 metadata] |
+
+```ts
+const historical = await client.credential.get({ ...management(cid),
+  audience: businessAid, metadata_version: historicalVersion,
+}, options);
+const revocationInput = { ...management(cid), reason_code: 'grant_withdrawn' };
+await app.save('revocation-input', revocationInput);
+const revoked = await client.credential.revoke(revocationInput, options);
+```
+
+get 使用当前、metadata_version、transition_id 三种选择之一。确认权按 confirmed_at 的固定依据核验；新修订重新确认，历史原件与回执继续保留供审计读取。
+
+### 4.8 额度、分配与执行结果（E27—E30）
+
+```mermaid
+flowchart TD
+    A[业务 allow 与新鲜状态] --> B[按 global／per_aud 计算全部适用账户]
+    B --> C{账本权威}
+    C -->|同权威| R[同事务预留父子账户]
+    C -->|跨权威| S[验 allocation 及在线 active 状态]
+    S --> T[预留本权威账户与已分配容量]
+    R --> D[按原业务键幂等执行]
+    T --> D
+    D -->|committed| E[结算累计值]
+    D -->|取消／确认无效果| F[释放预留]
+    D -->|Unknown| G[保留预留，查询原执行器]
+    G -->|确认成功| E
+    G -->|确认无效果| F
+```
+
+ledger／executor 为应用持久端口，额度使用精确十进制。跨权威先由父账本签 UsageAllocation 并验证在线状态；active 接受新预留，draining 结清在途，closed 返还剩余容量：
+
+```ts
+const signedAllocation = await client.credential.signAllocation(unsignedAllocation, parentLedgerSigner);
+const allocation = sp.decodeSignedJson(signedAllocation) as sp.UsageAllocation;
+await client.credential.verifyAllocation(allocation, {
+  ...trust, parent: parentEntry, child: childEntry, audience: request.aud,
+});
+const allocationBegan = performance.now();
+const allocationProof = await app.ledger.queryAllocation(allocation, allocationQuery);
+await client.credential.verifyAllocationStatus(allocationProof, { ...trust, allocation,
+  query: allocationQuery, elapsedSeconds: (performance.now() - allocationBegan) / 1000 });
+```
+
+sameAuthority 由已确认账本绑定计算；跨权威以已验真的 active 证明作为预留门槛：
+
+```ts
+if (sameAuthority || allocationProof?.state === 'active') {
+  const reservation = await app.ledger.reserveAll(request, demands);
+  const execution = await app.executor.executeOnce(request);
+  await app.ledger.recordOutcome(reservation, execution);
+}
+```
+
+### 4.9 UsageRef 切换与恢复（E31、E33）
+
+```mermaid
+sequenceDiagram
+    participant A as 协调应用
+    participant R as 登记权威
+    participant L as 原账本／新账本
+    A->>R: prepareUsage：固定 change 与 from/to UsageRef
+    R-->>A: prepared、transition_id、fence、candidate_hash
+    A->>L: 冻结、核对 Unknown、结清分配
+    L-->>A: checkpoints、allocation_closures、acceptances
+    alt 提交切换
+        A->>R: commitUsage：同 transition／fence
+        R-->>A: committed，全部 aud 原子发布
+    else 取消切换
+        A->>R: abortUsage：同 transition／fence／from_usage
+        R-->>A: aborted 与 recovery
+        A->>L: 按 recovery 收集 ledger-abort 确认
+    end
+```
+
+```ts
+const prepareInput = { ...management(cid), transition_id: transitionId,
+  from_usage: fromUsage, to_usage: toUsage, change: usageChange,
+  previous_abort_acks: previousAbortAcks } satisfies sp.SemanticUsageInput<'usage_prepare'>;
+await app.save('usage-prepare-input', prepareInput);
+const prepared = await client.credential.prepareUsage(prepareInput, options);
+await app.save('usage-transition', prepared);
+```
+
+```ts
+const commitInput = { ...management(cid), transition_id: prepared.transition_id,
+  fence: prepared.fence, checkpoints, allocation_closures: allocationClosures,
+  acceptances } satisfies sp.SemanticUsageInput<'usage_commit'>;
+await app.save('usage-commit-input', commitInput);
+const committed = await client.credential.commitUsage(commitInput, options);
+```
+
+```ts
+const abortInput = { ...management(cid), transition_id: prepared.transition_id,
+  fence: prepared.fence, from_usage: prepared.from_usage } satisfies sp.SemanticUsageInput<'usage_abort'>;
+await app.save('usage-abort-input', abortInput);
+const aborted = await client.credential.abortUsage(abortInput, options);
+```
+
+commit／abort 为两条分支。调用前保存各自输入；丢响应或重启后，用原 transition_id 查询 get，再按 prepared／committed／aborted 续跑。切换材料绑定同一 candidate_hash／UsageRef／fence，账户逐键连续；Unknown 继续保留预留与冻结，恢复资格取已签 recovery。
+
+### 4.10 CRL、冷恢复与双域（E21、E32—E36）
+
+```mermaid
+flowchart LR
+    A[原 AID、持久 store 与 authority／scope] --> B[从保存 cursor／after 开始拉页]
+    B --> C[facade 验签并原子合并页与进度]
+    C -->|next_cursor 有值| B
+    C -->|next_cursor=null| D[推进 upper_event_seq]
+    D --> E[恢复原业务请求与 transition]
+    E --> F[重新取得当前状态，续查原执行结果]
+```
+
+首次完整分页从 cursor=null 开始；续页沿用 scope、after_event_seq 和 limit，每页生成并保存独立管理请求：
+
+```ts
+let cursor: string | null = null;
+do {
+  const pageInput = { ...management(''), credential_cid: '' as const, scope,
+    after_event_seq: afterEventSeq, cursor, limit: 100 };
+  await app.save('crl-page-input', pageInput);
+  const page = await client.credential.revocations(pageInput, options);
+  cursor = page.next_cursor;
+  if (cursor === null) await app.saveCrlProgress(scope, page.upper_event_seq);
+} while (cursor !== null);
+```
+
+scope 变化使用独立进度。恢复保留 SDK 的语义持久状态、原请求和账本预留；online 重新查询。归档保存原件、历史修订、证书与解密能力，retain_until 按留存策略持久记录。
+
+```ts
+const remote = await client.credential.get({ ...management(remoteCid),
+  authority: remoteAuthority, audience: businessAid,
+}, { serviceAid: 'credential.aid.com', verificationContext: remoteTrust });
+```
+
+跨域逐层通过 packageContext.serviceFor 选择可信登记权威，并为归档配置对应 resolver／ACL。TS／JS 使用 {serviceAid}，Python 使用 target，Go 使用 NewCredentialFacade(client, serviceAID)；low-level、CLI 与浏览器映射见[移植指南 §4](凭证与组织服务SDK开发与移植指南.md#4-语义凭证移植契约)。
+
+### 4.11 E2E 场景对照
+
+| 场景 | 图与示例位置 |
+| --- | --- |
+| E01 普通兼容 | §3、§5—§7；移植指南 §3、§5—§7 |
+| E02—E05、E18 签发／补确认／确认权 | §4.2、§4.6—§4.7 |
+| E06—E11、E15 消息／上下文／附件 | §4.3、§4.6 |
+| E12—E16 交付／多跳／旧根／代表 | §4.4、§4.6 |
+| E17 多受众 CAS／历史 | §4.7 |
+| E19—E22 状态／撤销／角色变化 | §4.5、§4.7、§4.10 |
+| E23—E26 三态／本次确认／缓存／重传 | §4.4—§4.6 |
+| E27—E30 Unknown／累计额度／父子／跨权威 | §4.8 |
+| E31 UsageRef 切换 | §4.9 |
+| E32—E36 归档／重启／证书／双域／公开入口 | §4.3、§4.6、§4.10；移植指南 §4.5—§4.9 |
+
+场景逐项来源：[scenarios.json](../../examples/semantic-credential/scenarios.json)及[真实 E2E runner](../../tests/cross-sdk/runner/run_cross_sdk_e2e.py)。本轮实际覆盖为 CN、四 SDK、本地 CN↔aid.com、真实浏览器及持久恢复；固定模型、TTL 与留存证据边界见[示例使用指南](../../examples/semantic-credential/示例使用指南.md#5-本轮验证记录与边界)。
+
+## 5. 组织成员流程
+
+### 5.1 组织创建
+
+```mermaid
+flowchart LR
+    A[owner 会话和持久 AIDStore] --> B[生成并保存组织实体身份]
+    B --> C[准备 owner binding、CAP 和登记授权]
+    C --> D[Org 登记 CAP、验回执并创建组织]
+    D --> E[实体主签，owner token 上传名片]
+```
+
+```ts
+const created = await ownerClient.createOrg(
+  { org_id: orgAid, name: '协作组织' }, { aidStore: ownerStore },
+);
+```
+
+组织名片实体主签、owner token 上传，含当前 owner／实体指纹，附签存在则全验。组织不走通用 Ownership 绑定，名片待办与创建结果分开。
+
+### 5.2 申请加入与邀请
+
+```mermaid
+sequenceDiagram
+    participant M as 成员 App
+    participant O as owner／管理员 App
+    participant G as Org 服务
+    participant C as Credential 服务
+    alt 成员申请
+        M->>G: join：成员签 binding
+        G-->>O: 待审批
+        O->>G: approveJoin：审批者签 binding，实体签 CAP／登记授权
+    else 组织邀请
+        O->>G: invite：每个目标独立 binding／CAP／登记授权
+        G-->>M: 原邀请材料
+        M->>G: inviteAccept：保留原材料，补目标成员签名
+    end
+    G->>C: 登记成员 CAP
+    C-->>G: 签名回执
+    G->>G: 验回执并最终化成员
+    G-->>M: active 与完整成员包
+```
+
+成员申请：
+
+```ts
+const joinParams = memberClient.org.prepareRequest('org.member.join', {
+  org_id: orgAid, member_type: 'human', requested_role: 'member', terms,
+}, orgServiceAid, memberSigner);
+const application = await memberClient.org.member.join(joinParams);
+```
+
+审批端从原申请取得 applicationBinding／terms；ownerSigner 签 binding 的组织侧，orgSigner 签 CAP 和登记授权，ownerCredentials 提供审批资格：
+
+```ts
+const binding = ownerClient.org.member.signBinding(applicationBinding, ownerSigner, 'org');
+const approval = ownerClient.org.prepareRequest('org.member.approveJoin', {
+  org_id: orgAid, terms, membership_binding: binding, credentials: ownerCredentials,
+}, orgServiceAid, ownerSigner, { orgSigner });
+await ownerClient.org.member.approveJoin(approval);
+```
+
+邀请端逐目标生成材料：
+
+```ts
+const invitationParams = ownerClient.org.prepareRequest('org.member.invite', {
+  org_id: orgAid, targets: [holderAid], terms, credentials: ownerCredentials,
+}, orgServiceAid, ownerSigner, { orgSigner });
+const invitations = await ownerClient.org.member.invite(invitationParams);
+```
+
+invitation 取返回 invites[] 中当前成员的一项；接收端组装接受请求：
+
+```ts
+const accepted = memberClient.org.prepareRequest('org.member.inviteAccept', {
+  org_id: orgAid, invite_id: invitation.invite_id,
+  membership_binding: invitation.membership_binding,
+  credential_template: invitation.credential_template,
+  registration_authorization: invitation.registration_authorization,
+}, orgServiceAid, memberSigner);
+await memberClient.org.member.inviteAccept(accepted);
+```
+
+首次入组绑定 membership_id 和原 request ID／nonce，不带 CID／已有 CAP。本人和代表均须目标成员签名；for≠signer.aid 另验代表证明和当前 Ownership／actor 状态。
+
+### 5.3 查询、状态变更与续期
+
+```mermaid
+flowchart LR
+    A[同一成员关系，准备新 binding／CAP／登记授权] --> B[renewCredential：旧 CID＋当前版本 CAS]
+    B --> C[登记新 CAP 并验回执]
+    C -->|成功| D[提交新成员版本，再撤旧 CAP]
+    C -->|失败| E[仅补偿撤新 CAP]
+    D --> F[立即保存完整新成员包]
+```
+
+renewalMaterial 含旧 CID、expected_version、双签新 binding、terms、新 CAP／登记授权及当前调用授权：
+
+```ts
+const renewal = memberClient.org.prepareRequest(
+  'org.member.renewCredential', renewalMaterial, orgServiceAid, memberSigner,
+);
+await memberClient.org.member.renewCredential(renewal);
+const current = await memberClient.credential.current(memberCredential);
+```
+
+续期保持原成员关系，响应后立即持久完整成员包，credential.current 无需等事件。长期凭证 READY 后及在线每60秒扫描，显式短期凭证不自动续期。
+
+当前资格看签名 membership_status：banned／ended 拒绝，frozen 禁普通写，offboarding 仅收尾。离职按 leave/kick→offboard→ended→撤有权吊销的 CAP→清 active projection，失败续跑。
+
+## 6. 组织请求与跨设备代表
+
+### 6.1 统一请求准备
+
+```mermaid
+flowchart LR
+    A[业务参数＋本次授权包] --> B[prepareRequest：原 ID／nonce、AAD、request binding]
+    B --> C[必要时补代表证明]
+    C --> D[RPC 管线生成外层 client_signature]
+    D --> E[Gateway service-plane]
+    E --> F[服务独立重算签名、摘要和当前权限]
+```
+
+受保护读取也须准备请求，例如查询自己的成员状态：
+
+```ts
+const params = memberClient.org.prepareRequest('org.member.get', {
+  org_id: orgAid, member_aid: memberSigner.aid, credentials: memberCredentials,
+}, orgServiceAid, memberSigner);
+const member = await memberClient.org.member.get(params);
+```
+
+准备后原样发送，RPC 管线补 client_signature。受保护读取也需当前 binding／CAP；公开 lifecycle.get/list 按可见性处理。AAD 绑定 org_id，仅 lifecycle.list／health／status 可为 null。
+
+### 6.2 代表操作
+
+参数增加 for: holderAid，授权包仍属 holder。prepareRequest 绑定双方、方法、服务、摘要和时间窗；首次 admission 绑定 membership_id，其他代表绑定 CID。owner 不能替代目标成员签名。
+
+### 6.3 服务事件
+
+SDK 验服务、接收 AID、证书、签名和时间窗后去重；撤销同步如下：
+
+```mermaid
+flowchart LR
+    A[撤销推送／已签列表页] --> B[验签及身份／连接代次复核]
+    B --> C[按 authority、CID 保留最大 event_seq]
+    C --> D[持久保存快照]
+    D --> E[后续授权检查使用]
+```
+
+单条推送不推进分页，旧页不覆盖新证据，本地缺 CID 不证明有效。连接后一小时首次兜底拉列表，之后每小时；重连重新计时，与60秒凭证扫描独立。
+
+## 7. 所有权转让与实体材料
+
+```mermaid
+sequenceDiagram
+    participant O as 原 owner
+    participant N as 目标 owner SDK
+    participant G as Org 服务
+    participant CA as CA
+    O->>G: transfer：当前授权请求
+    G-->>N: transfer proposal
+    N->>N: 签接受材料，持久保存新 P-256 私钥与 checkpoint
+    N->>G: transferAccept stage=rekey
+    G->>CA: 复核代际并提交新公钥
+    CA-->>G: 新实体证书
+    G-->>N: pending_finalization 与新证书
+    N->>N: 导入证书，重签新旧 owner binding／CAP
+    N->>G: stage=finalize，独立持久 request ID
+    G->>G: 新 owner 生效，旧 owner 降 member，撤旧 CAP
+    N->>N: 新实体主签，owner token 上传名片
+```
+
+原 owner 调用 org.lifecycle.transfer。目标验证 proposal 后签接受字段：
+
+```ts
+const acceptance = targetClient.org.lifecycle.signTransferAcceptance(proposal, targetSigner);
+```
+
+transferParams 合并 acceptance、原 proposal、双方完整成员材料及授权包：
+
+```ts
+const transferred = await targetClient.completeOrgTransfer(
+  transferParams, { aidStore: targetStore },
+);
+```
+
+恢复沿用原 transfer ID、输入、阶段参数和私钥；缺 key 报 persistence_unavailable，材料变化报 conflict，TS／JS 精确完成态可重放。详见 [移植 §7](凭证与组织服务SDK开发与移植指南.md#7-高层实体身份和转让编排)。
+
+解散用 client.dissolveOrg(params, { aidStore })，提供当前 binding／CAP；确认 dissolved 后才失效本地证书并清恢复状态，保留磁盘私钥。名片失败稿保留完整多签、固定 owner／代际和原 CAS，仅显式重试，重连不 PUT；代际变化停止旧待办。
+
+## 8. 四端入口速查
+
+| 能力 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| 业务入口 | client.credential／org | client.credential／org | client.Credential()／Org() |
+| 请求准备 | org.prepare_request | org.prepareRequest | Org().PrepareRequest |
+| 组织创建／转让 | org.lifecycle.create／transfer_accept | createOrg／completeOrgTransfer | CreateOrg／CompleteOrgTransfer |
+
+本节普通凭证／Org 的 Node TS 协议 helper 同步，浏览器密码 helper 为 Promise；Python RPC async／协议 helper 同步，Go 返回 value/error。文件 AIDStore.sign/verify 的 TS／JS 均须 await；语义 facade 的异步约定见§4。
+
+## 9. 错误与重试
+
+仅重试读取或原 method／request ID／摘要不变的幂等操作。签名／权限／binding／状态／幂等冲突不盲重试；未知暂缓副作用，创建补偿遇幂等冲突停自动补偿。
+
+跨期恢复只确认原期限内已持久且已发送的既成结果，不重登记／重签。无原回执时只保存 issuer 结果，holder 交付仍需原有效回执，边界见 [移植 §5.2](凭证与组织服务SDK开发与移植指南.md#52-登记授权和回执)。
+
+## 10. 验收清单
+
+覆盖完整 Verify、回执、双签入组、受保护读取、撤销乱序／重启、续期完整包、转让两阶段丢响应。运行见 [测试指南](../aun测试运行指南.md)，版本边界见 [四端对齐清单](../../python/CHANGES_FOR_PARITY.md)。