@tier0/sdk-v2 0.9.9 → 0.9.10

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/delete.md

@@ -1,56 +1,62 @@
 # 删除记录与元数据
 
-记录删除仍使用专属数据接口：
+记录删除使用专属数据接口，`expectedRevision` 取自已有记录或最近写回执；没有版本时再读取：
 
 ```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type UnsV2Integer } from '@tier0/sdk-v2';
 
 export async function deleteDevice(
-  collectionId: string, id: string, intentKey: string, client: Tier0Client = createClient(),
+  collectionId: string, id: string, expectedRevision: UnsV2Integer,
+  intentKey: string, client: Tier0Client = createClient(),
 ) {
-  const current = (await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 })).data.items[0];
-  if (!current) throw new Error('记录不存在或不可见，未执行删除');
   const receipt = await client.uns.recordDeleteOne({
-    collectionId, filter: { _id: id }, expectedRevision: current.revision,
+    collectionId, filter: { _id: id }, expectedRevision,
     dryRun: false, idempotencyKey: intentKey,
   });
   if (receipt.data.status !== 'committed' || String(receipt.data.deletedCount) !== '1') {
     return { state: 'unconfirmed' as const, receipt };
   }
-  const after = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  if (after.data.items.length) throw new Error('删除有回执，但记录仍可见或已被恢复');
   return { state: 'committed' as const, receipt };
 }
 ```
 
-元数据使用 metadataDeleteOne/Many，或 metadataDeleteOne + returnDocument:before 返回删除前对象。它们执行软删除，增加 revision，不隐式级联目录后代、引用对象或集合数据。集合有 Record/Sample 或配置引用不阻止明确删除；引用方保留并得到目标已删除的结果。目录和 Topic 保留原有约束，不能自行扩展删除范围。已知 revision 可直接提交，不要求每次重新读取或先 dryRun。
+元数据使用 metadataDeleteOne/Many；需要删除前对象时传 returnDocument:before。已知 revision 可直接提交，不要求重新读取或先 dryRun。
 
 ```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type UnsV2Integer } from '@tier0/sdk-v2';
 
 export async function deleteCollection(
-  id: string, intentKey: string, client: Tier0Client = createClient(),
+  id: string, expectedRevision: UnsV2Integer,
+  intentKey: string, client: Tier0Client = createClient(),
 ) {
-  const current = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, limit: 1 })).data.items[0];
-  if (!current) throw new Error('集合不存在或不可见，未执行删除');
   const receipt = await client.uns.metadataDeleteOne({
-    kind: 'collection', filter: { _id: id }, expectedRevision: current.revision,
+    kind: 'collection', filter: { _id: id }, expectedRevision,
     dryRun: false, idempotencyKey: intentKey,
   });
   if (receipt.data.status !== 'committed' || String(receipt.data.deletedCount) !== '1') {
     return { state: 'unconfirmed' as const, receipt };
   }
-  const deleted = await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, state: 'deleted', limit: 1 });
-  if (!deleted.data.items[0]) throw new Error('删除有回执，但删除状态读回未确认');
-  return { state: 'deleted' as const, receipt, deleted: deleted.data.items[0] };
+  return { state: 'deleted' as const, receipt };
 }
 ```
 
-metadataDeleteMany 使用明确 filter 和 maxDocs。默认原子；超过上限整体拒绝，不会静默只删第一批。批量删除前可 dryRun。state 默认 active，删除对象通过 state=deleted 查询；all 同时包含两种状态。
+metadataDeleteMany 使用明确 filter 和 maxDocs。默认原子；超过上限整体拒绝。目录删除的 maxDocs 与 deletedCount 只计显式匹配项，不计隐式级联后代；服务端会去重父子项，无需逐个删除后代。需要预览时可 dryRun。state 默认 active，回收对象通过 state=deleted 查询；all 包含两种状态。
+
+## 回收规则
+
+软删除增加 revision，保留 Record、Sample 与查询索引；历史按既有授权只读，数据写入和后台 TTL 清理停止。外部引用不阻止回收，引用方配置保留；删除 Topic 不删除其引用的 Collection。
+
+| 操作 | 范围与授权 |
+| --- | --- |
+| 元数据软删除 | 目录在同一事务内回收有效子树；此前独立回收的对象不加入本次批次。既有授权保留。 |
+| App 集合 archive | 归档指定自有集合，撤销调用 App 对它的 grant；其他未撤销授权仍可读取历史。 |
+| App 移入回收站 | 停用该 App，联动回收其自有集合和明确专属目录；借用集合、共享目录保留，其他活跃授权主体仍可读取历史。 |
+
+恢复范围和授权区别见[恢复](restore.md)。保留的物理索引仍占配额，归档不释放索引空间。
 
 业务记录使用 recordDeleteOne/Many，传 collectionId 和明确 filter，编辑型流程同时传 expectedRevision。不要把元数据软删除解释成逐条删除该集合的 Record。Sample 的删除是独立的显式时间范围操作，具体影响遵循当前数据 API 契约。
 
-恢复见[恢复](restore.md)。未知写入结果保留原意图键，先按对象身份核对，不自动换键重试。
+成功回执已确认本次操作，不再固定读回验证。结果未知时保留原意图键，按对象身份核对；需要展示最新状态时再刷新。版本冲突应重新读取并由调用方处理，不自动覆盖。
 
 ## 永久删除回收站集合
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/namespace.md

@@ -6,8 +6,8 @@
 
 | 凭证 | Namespace / metadata 查询 | 发现并读取集合 |
 | --- | --- | --- |
-| 未绑定 App 的 Agent / Personal Key | 有当前工作空间权限及 Key scope 时可用；Agent Key 还会复核真实负责人的状态和权限 | 按当前工作空间授权查询，再调用 `recordFind` |
-| App Key | 当前不开放；`appCollectionsList` 也不能调用 | `dataAppContext({})` 返回自有及已授权集合、目录路径、结构和有效权限，再按集合 ID 调 `recordFind` |
+| 未绑定 App 的 Agent / Personal Key | 有当前工作空间权限及 Key scope 时可用；Agent Key 还会复核真实负责人的状态和权限 | 已知集合 ID 时直接调用 `recordFind`；需要发现集合时按工作空间权限查询元数据 |
+| App Key | 当前不开放；`appCollectionsList` 也不能调用 | 已知集合 ID 时直接调用 `recordFind`；需要发现集合及结构时使用 `dataAppContext({})` |
 | 平台系统 Service Key | 按实际系统凭证授权，不按“Agent 正在调用”推定权限 | 带 Builder 目标时，指定 App 操作可使用目标 App 视角；不代表所有查询都变成 App 视角 |
 
 目录位置不产生数据授权。App 自有集合的正常创建流程提供相应授权，但读取仍受凭证权限、App 状态及数据策略约束；不能仅凭 `ownerAppId` 推定任何接口都可调用。SDK 和 MCP 使用相同凭证时仍受服务端授权约束。
@@ -60,4 +60,4 @@ export async function createDirectoryAndTopic(
 
 transact 始终原子，结果通过 opId 对应输入；dryRun=true 校验，不预留 ID 或名称。正式执行仍重新检查。创建结果引用仅用于契约支持的关系字段，不能把任意字符串或脚本当引用。
 
-名称、父目录、Schema、引用与权限由服务端校验。移动不改变对象 ID；删除目录不隐式清空后代；删除 Topic 不删除所引用的 Collection。引用查询仍使用 references 专用方法。
+名称、父目录、Schema、引用与权限由服务端校验。移动不改变对象 ID；删除目录原子回收有效子树，删除 Topic 不删除所引用的 Collection。外部引用不阻止回收；范围、授权和恢复规则见[删除](delete.md#回收规则)与[恢复](restore.md)。引用查询仍使用 references 专用方法。

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/read.md

@@ -2,7 +2,7 @@
 
 ## App Key：从授权上下文读取
 
-App Key 使用 `dataAppContext`，不调用 `namespace`、`metadataFind` 或 `appCollectionsList`。上下文包含可访问集合的名称、目录路径、Schema 和有效权限；按已配置 alias 精确定位，不能随意选择列表第一项。已知集合 ID 时可直接调用 `recordFind`，不要求每次预先加载上下文。
+App Key 已知集合 ID 时直接调用 `recordFind`；需要发现集合时使用 `dataAppContext`，不调用 `namespace`、`metadataFind` 或 `appCollectionsList`。上下文包含可访问集合的名称、目录路径、Schema 和有效权限；按已配置 alias 精确定位，不能随意选择列表第一项。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
@@ -55,3 +55,9 @@ export async function listCollections(page = 1, client: Tier0Client = createClie
 按 pageInfo.hasMore/nextPage 继续元数据分页；不要把第一页当全量。recordFind 的游标循环见[数据工作流](data-workflows.md)。sort 是数组元组。
 
 以上 metadataFind 示例用于 Workspace 集成（会话、personal / agent Key）。App 凭证不能调用 metadataFind：用 dataAppContext 精确选择授权 alias，集合的 revision、indexStatus、ttl 也在其中。数据授权不等于元数据管理授权。网络/权限错误必须传播，不能用空数组掩盖错误。
+
+## 回收集合的历史读取
+
+按原 collectionId 读取 Record、Sample、count 或 aggregate；既有授权、员工行规则和字段权限仍生效。活跃 Topic 可继续读取其引用的回收集合。活跃 App 的 dataAppContext 保留仍可读的回收集合，但不授予新增能力；回收中的 App 自身不能运行。
+
+已知 ID 直接读取，不必先恢复集合或查询元数据。数据层也可用 `data.collection({ collectionId })`，不会 ensure、写种子或补授权。只有 Workspace 集成确需回收对象定义时，才用 metadataFind 的 state=deleted 或 all；App Key 仍不调用该接口。[回收规则](delete.md#回收规则)说明写入和恢复边界。

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/restore.md

@@ -1,24 +1,25 @@
 # 恢复元数据与记录
 
-metadataRestore 接收 kind、items[{id,expectedRevision?}]，支持一个或多个明确 ID。revision 应从 state=deleted 的当前对象读取。恢复重新校验名称、父目录、Schema 与引用；不会恢复其他对象，冲突时原子批次回滚。
+metadataRestore 接收 kind、items[{id,expectedRevision?}]。编辑流程复用回收列表中的 revision，没有版本时再用 state=deleted 读取。恢复由服务端校验名称、父目录、Schema 与引用，冲突时原子批次回滚。
+
+恢复目录会一并恢复同次回收的子树，此前独立回收的对象保持原状态。随目录回收的子项应通过原目录恢复；单独恢复返回 CONDITION_FAILED / DIRECTORY_IN_TRASH。无需枚举子项逐个恢复；若请求同时列出父子项，服务端仍检查每项 expectedRevision。
+
+随 App 回收的对象通过恢复原 App 处理，此前独立回收的对象保持原状态；OWNER_APP_TRASHED 不应触发重建或写入重试。通用元数据恢复不补回撤销的 grant；App 集合 restore 则恢复该 alias 最近归档的集合并重新授权。此前独立删除的记录不会随集合恢复。当前 archive / restore 不逐条重写记录；2000 条上限仅适用于旧 recordsArchivedAt 墓碑恢复。
 
 ```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type UnsV2Integer } from '@tier0/sdk-v2';
 
 export async function restoreCollection(
-  id: string, intentKey: string, client: Tier0Client = createClient(),
+  id: string, expectedRevision: UnsV2Integer,
+  intentKey: string, client: Tier0Client = createClient(),
 ) {
-  const deleted = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, state: 'deleted', limit: 1 })).data.items[0];
-  if (!deleted) throw new Error('未找到待恢复集合');
   const receipt = await client.uns.metadataRestore({
-    kind: 'collection', items: [{ id, expectedRevision: deleted.revision }], idempotencyKey: intentKey,
+    kind: 'collection', items: [{ id, expectedRevision }], idempotencyKey: intentKey,
   });
   if (receipt.data.status !== 'committed' || String(receipt.data.restoredCount) !== '1') {
     return { state: 'unconfirmed' as const, receipt };
   }
-  const current = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, limit: 1 })).data.items[0];
-  if (!current) throw new Error('恢复有回执，读回未确认');
-  return { state: 'committed' as const, receipt, current };
+  return { state: 'committed' as const, receipt };
 }
 
 export async function restoreDevice(
@@ -30,10 +31,8 @@ export async function restoreDevice(
   if (receipt.data.status !== 'committed' || !receipt.data.restoredIds.includes(id)) {
     return { state: 'unconfirmed' as const, receipt };
   }
-  const found = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  if (!found.data.items[0]) throw new Error('恢复有回执，读回未确认');
-  return { state: 'committed' as const, receipt, current: found.data.items[0] };
+  return { state: 'committed' as const, receipt };
 }
 ```
 
-Record 恢复使用 recordRestore 的 ids（最多 100 条），重新校验当前 Schema 和有效唯一索引，冲突整批回滚。新增同 ID 或 upsert 不会隐式恢复对象。幂等键每个新意图独立。
+Record 恢复使用 recordRestore 的 ids（最多 100 条），重新校验当前 Schema 和有效唯一索引，冲突整批回滚。新增同 ID 或 upsert 不会隐式恢复对象。幂等键每个新意图独立；结果未知时核对原对象，正常成功无需额外读回。需要最新快照时，元数据恢复可使用回执 items，记录恢复可按需查询。