@tier0/sdk-v2 0.9.9 → 0.10.0

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/create.md

@@ -6,14 +6,14 @@
 | --- | --- | --- | --- |
 | dryRun | boolean | 否 | 默认 false 提交；true 仅预检 |
 | program.name | string | 是 | 1–63 字符 |
-| program.script | string | 是 | 完整 module.exports 程序 |
-| program.timeoutMs | integer | 否 | 当前云端上限 30000 ms |
+| program.script | object | 是 | code 为完整 module.exports 程序，timeoutMs 为超时 |
+| program.script.timeoutMs | integer | 是 | 当前云端上限 30000 ms |
 | program.sourceBindings | array | 否 | sourceId、configRevision、acquisition |
 | idempotencyKey | string | 否 | 最多 128 字符，本次创建的固定意图键 |
 
 ## HTTP Client Source 绑定示例
 
-先按[Source 查询](../../tier0-sdk-v2-source/references/read.md)选定真实 HTTP Client Source。脚本的 api.sources 属于平台执行器，与应用中的 client.source 不同。sourceId 保持字符串，configRevision 使用 Source 创建、更新回执或完整查询得到的修订。已有回执时直接传入 source；没有快照时再调用 source.documents.get({id,view:"full"}) 并检查 data.document。省略 `config.role` 时按正式协议目录默认为 client；Server 走入站语义，不能创建为主动请求程序。
+先按[Source 查询](../../tier0-sdk-v2-source/references/read.md)选定真实 HTTP Client Source。脚本的 api.sources 属于平台执行器，与应用中的 client.source 不同。sourceId 保持字符串，configRevision 使用 Source 创建、更新回执或完整查询得到的修订。已有回执时直接传入 source；没有快照时再调用 source.documents.get({id,view:"full"}) 并检查 data.document。省略 `role` 时按正式协议目录默认为 client；Server 走入站语义，不能创建为主动请求程序。
 
 Source 负责基址和认证，Stream 负责请求的 method/path/query。以下示例与 [Source Bearer 创建](../../tier0-sdk-v2-source/references/create.md#http-client-bearer-凭据)配合：Source endpoint 为 `https://inventory.example.com/api/v1`，凭据使用默认基址绑定；实际请求是 `GET https://inventory.example.com/api/v1/inventory?limit=5000`。已有 Source 的凭据若只绑定精确 URL `/api/v1` 的 GET，不能用于此子路径；不要通过改写请求为 REQUEST 或自动扩大凭据授权来绕过拒绝。
 
@@ -26,14 +26,14 @@ export async function createHttpStream(
   if (!collectionId.trim()) throw new Error('需要实际 Collection ID');
   const sourceId = source.id;
   if (!/^[1-9][0-9]*$/.test(sourceId)) throw new Error('Source ID 必须是正十进制字符串');
-  if (source.document.protocol !== 'http-api' || 'sourceType' in source.document.config ||
-      (source.document.config.role ?? 'client') !== 'client') {
+  if (source.document.protocol !== 'http-api' || 'sourceType' in source.document ||
+      (source.document.role ?? 'client') !== 'client') {
     throw new Error('此主动请求示例需要 HTTP API Client Source');
   }
   const document: RuntimeStreamDefinition = {
-    name, timeoutMs: 5000,
+    name,
     sourceBindings: [{ sourceId, configRevision: source.revision, acquisition: {} }],
-    script: [
+    script: { timeoutMs: 5000, code: [
       'module.exports = api => {',
       '  const upstream = api.sources.use({ id: ' + JSON.stringify(sourceId) + ', resources: [] });',
       '  const output = api.uns.use({ collectionId: ' + JSON.stringify(collectionId) + ', access: "write" });',
@@ -49,7 +49,7 @@ export async function createHttpStream(
       '    return { acceptedRows: records.length };',
       '  });',
       '};',
-    ].join('\n'),
+    ].join('\n') },
   };
   const saved = await client.stream.documents.create({
     dryRun: false, program: document, idempotencyKey: intentKey,
@@ -73,4 +73,18 @@ validate 检查配置、程序和可确定的绑定问题，不执行任意业
 
 创建结局未知时先按已知 ID 或业务标识核对状态；允许重试时保留原请求与幂等键。
 
-原生编辑器形态 `documents.create({dryRun, document})` 的 document 为 name/model/script对象/sources/entries，script 为 `{code,timeoutMs}`，sources 用 alias/sourceId/configRevision/resources/acquisition。不要把上面的 script 字符串直接塞入原生文档。
+原生编辑器形态 `documents.create({dryRun, document})` 的 document 为 name/model/script对象/sources/entries，script 为 `{code,timeoutMs}`，sources 用 alias/sourceId/configRevision/resources/acquisition。两种入口均使用 script 对象；不接受 script 字符串。
+
+远端 Edge 绑定使用 `target: {fleetNodeId, sourceId, configRevision}` 替代同一绑定上的 sourceId/configRevision。fleetNodeId 是发现返回的复合节点字符串，sourceId 是该节点上的原生十进制 ID。服务端验证并创建引用，调用方不拼装 edge:// 引用，也不创建另一种 Source 文档。
+
+```ts
+import type { RuntimeStreamDefinition, StreamSourceTarget } from '@tier0/sdk-v2';
+
+export function bindApprovedEdgeSource(
+  program: RuntimeStreamDefinition, target: StreamSourceTarget,
+): RuntimeStreamDefinition {
+  return { ...program, sourceBindings: [{ target, acquisition: {} }] };
+}
+```
+
+该函数只构造绑定；脚本仍须使用声明资源并通过目标目录授权。厂商凭据在 Edge 本地预配，target 不携带秘密。配置成功不证明端到端采集完成。

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/deploy.md

@@ -4,18 +4,18 @@
 | --- | --- | --- |
 | programs.deploy | /openapi/v2/uns/streams/program/deploy | id；dryRun 默认 false，建议 expectedRevision 和发布状态守卫 |
 | programs.rollback | /openapi/v2/uns/streams/program/rollback | id、versionId、dryRun；建议 expectedRevision 和发布状态守卫 |
-| documents.disable | /openapi/v2/uns/streams/documents/disable | id、expectedRevision、expectedActiveRelease、dryRun |
+| documents.disable | /openapi/v2/uns/streams/documents/disable | id、expectedRevision、expectedActiveVersion、dryRun |
 
 全部写操作使用各自的 idempotencyKey。expectedSourceRevision 只适用于恰好一个 Source 依赖，且同时保护草稿冻结修订与当前 Source head；多源不能塞入单个修订值。原生文档没有 documents.deploy，当前云端 program 模型发布走 programs.deploy。
 
-发布和回滚有可选并发守卫：有生效发布时传入正整数 `expectedActiveRelease`；没有生效发布时传入 `expectedReleaseState: 'inactive'`，两者不能同时使用。服务端在事务内比较当前状态，变化时返回版本冲突；重新读取并决策后才能使用新的业务意图。守卫比较当前值，不记录中间发生的全部切换。
+发布、停用和回滚使用 `expectedActiveVersion` 并发守卫：传服务端回执的十进制字符串 activeVersion，'0' 表示无生效发布。它是不可推算的发布 ID，不是 activeRelease 序号；不再传 expectedReleaseState。服务端在事务内比较当前状态，变化时返回版本冲突；重新读取并决策后才能使用新的业务意图。守卫比较当前值，不记录中间发生的全部切换。
 
 发布、停用和回滚需要 uns.stream.manage；相关 Source 访问还受各自授权约束。保存回执中的 revision、发布回执中的 activeVersion 与 activeRelease 分别用于不同目的：
 
 | 字段 | 含义与用途 |
 | --- | --- |
 | revision | 草稿修订；传给下次写入的 expectedRevision，冲突时显式处理 |
-| activeVersion | 不可变发布版本 ID；回滚的 versionId 使用这个 ID，不使用发布序号 |
+| activeVersion | 十进制字符串形式的不可变发布 ID；用于 expectedActiveVersion 与回滚 versionId，不由 activeRelease 序号推算 |
 | activeRelease | 本次事务记录的正整数发布序号；与 runs.list 中的 release 对照；无活跃发布或回执未记录时省略 |
 
 programs 回执的 activeVersion:'0' 表示无活跃版本；programs 的 activeRelease 此时省略；documents 的 activeRelease 此时为 0。
@@ -24,11 +24,12 @@ programs 回执的 activeVersion:'0' 表示无活跃版本；programs 的 active
 import { createClient, type Tier0Client, type CloudStreamDocumentView, type CloudStreamStopView } from '@tier0/sdk-v2';
 
 export async function deployStream(current: CloudStreamDocumentView, intentKey: string, client: Tier0Client = createClient()) {
+  if (typeof current.activeVersion !== 'string' || !/^(0|[1-9][0-9]*)$/.test(current.activeVersion)) throw new Error('缺少权威 activeVersion；读取当前文档后再决定');
   const sources = current.document.sources ?? [];
   const request = {
     id: current.id, expectedRevision: current.revision,
-    ...(String(current.activeRelease) === '0' ? { expectedReleaseState: 'inactive' as const } : { expectedActiveRelease: current.activeRelease }),
-    ...(sources.length === 1 ? { expectedSourceRevision: sources[0]!.configRevision } : {}),
+    expectedActiveVersion: current.activeVersion,
+    ...(sources.length === 1 && !sources[0]!.target ? { expectedSourceRevision: sources[0]!.configRevision } : {}),
   };
   const receipt = await client.stream.programs.deploy({
     ...request, dryRun: false, idempotencyKey: intentKey,
@@ -44,22 +45,22 @@ export async function deployStream(current: CloudStreamDocumentView, intentKey:
 }
 
 export async function disableStream(
-  current: Pick<CloudStreamStopView, 'id' | 'revision' | 'activeRelease'>,
+  current: Pick<CloudStreamStopView, 'id' | 'revision' | 'activeVersion'>,
   intentKey: string, client: Tier0Client = createClient(),
 ) {
-  if (BigInt(String(current.activeRelease)) <= 0n) throw new Error('没有活跃发布可停用');
+  if (typeof current.activeVersion !== 'string' || !/^[1-9][0-9]*$/.test(current.activeVersion)) throw new Error('没有已确认的活跃版本可停用');
   const receipt = await client.stream.documents.disable({
-    id: current.id, expectedRevision: current.revision, expectedActiveRelease: current.activeRelease,
+    id: current.id, expectedRevision: current.revision, expectedActiveVersion: current.activeVersion,
     dryRun: false, idempotencyKey: intentKey,
   });
-  if (!('id' in receipt.data) || String(receipt.data.activeRelease) !== '0') {
+  if (!('id' in receipt.data) || receipt.data.activeVersion !== '0') {
     throw new Error('未返回停用回执');
   }
   return { receipt, current: receipt.data };
 }
 ```
 
-将创建或更新回执的 current 传给 deployStream，只发一次发布请求。只有手上没有草稿快照时才先 documents.get。使用 [按发布号查询运行记录](read.md#观察本次发布) 才能观察这次发布，观察窗口汇总不能证明该版本运行。发布成功不表示外部连接健康或执行成功。停用使用已确认的 id/revision/activeRelease（可来自发布回执），返回的 current 可直接用于删除；不需要前后各 get。停用保留草稿。仅修改草稿的任务不额外发布/停用。
+将创建或更新回执的 current 传给 deployStream，只发一次发布请求。只有手上没有草稿快照时才先 documents.get。使用 [按发布号查询运行记录](read.md#观察本次发布) 才能观察这次发布，观察窗口汇总不能证明该版本运行。发布成功不表示外部连接健康或执行成功。停用使用已确认的 id/revision/activeVersion（可来自发布回执），返回的 current 可直接用于删除；不需要前后各 get。停用保留草稿。仅修改草稿的任务不额外发布/停用。
 
 ## 回滚到明确版本
 
@@ -67,12 +68,13 @@ export async function disableStream(
 import { createClient, type Tier0Client, type CloudStreamStopView } from '@tier0/sdk-v2';
 
 export async function rollbackStream(
-  current: Pick<CloudStreamStopView, 'id' | 'revision' | 'activeRelease'>, versionId: string, intentKey: string, client: Tier0Client = createClient(),
+  current: Pick<CloudStreamStopView, 'id' | 'revision' | 'activeVersion'>, versionId: string, intentKey: string, client: Tier0Client = createClient(),
 ) {
   // versionId 使用已知发布回执的 activeVersion，或从 programs.versions.list 选定。
+  if (typeof current.activeVersion !== 'string' || !/^(0|[1-9][0-9]*)$/.test(current.activeVersion)) throw new Error('缺少权威 activeVersion；读取当前文档后再决定');
   return client.stream.programs.rollback({
     id: current.id, versionId, expectedRevision: current.revision,
-    ...(String(current.activeRelease) === '0' ? { expectedReleaseState: 'inactive' as const } : { expectedActiveRelease: current.activeRelease }),
+    expectedActiveVersion: current.activeVersion,
     dryRun: false, idempotencyKey: intentKey,
   });
 }

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/http-server.md

@@ -1,12 +1,12 @@
 # HTTPServer 固定前缀与 Stream 路由
 
-先用 [Source 创建](../../tier0-sdk-v2-source/references/create.md)保存 `http-api` + `config.role: server`。Source 使用 `http://managed` 和空 options；业务路径在 Stream 注册。
+先用 [Source 创建](../../tier0-sdk-v2-source/references/create.md)保存 `http-api` + `role: server`。Source 使用 `http://managed` ；业务路径在 Stream 注册。
 
 固定前缀为 `/ingest/v1/{workspaceId}/{sourceId}`。下例路由为 `POST /orders/:id`，完整请求路径为 `POST /ingest/v1/{workspaceId}/{sourceId}/orders/A-001`。前缀由部署环境和已认证的工作空间、Source 身份确定，不从请求 body 推断工作空间。Bearer 凭据由 Source 的既有管理合同取得并在调用时注入，不写入脚本。
 
 ## 保存原生程序草稿
 
-使用完整原生 `document`：script 是 `{code,timeoutMs}`，sources 使用 alias。这与 `program` 的 script 字符串形态不同。
+使用完整原生 `document`：script 是 `{code,timeoutMs}`，sources 使用 alias。这与 `program` 的 script 对象形态不同。
 
 ```ts
 import { createClient, type Tier0Client, type CloudStreamDocument } from '@tier0/sdk-v2';
@@ -18,7 +18,7 @@ export async function createHttpServerStream(
   if (!/^[1-9][0-9]*$/.test(sourceId)) throw new Error('Source ID 必须是正十进制字符串');
   const source = await client.source.documents.get({ id: sourceId, view: 'full' });
   if (!('document' in source.data)) throw new Error('需要完整 Source 文档');
-  const config = source.data.document.config;
+  const config = source.data.document;
   if (source.data.document.protocol !== 'http-api' || config.role !== 'server') {
     throw new Error('此入站路由示例需要 HTTP API Server Source');
   }
@@ -60,7 +60,7 @@ export async function createHttpServerEarlyReplyStream(
   if (!collectionId) throw new Error('需要实际 Collection ID');
   const source = await client.source.documents.get({ id: sourceId, view: 'full' });
   if (!('document' in source.data)) throw new Error('需要完整 Source 文档');
-  const config = source.data.document.config;
+  const config = source.data.document;
   if (source.data.document.protocol !== 'http-api' || config.role !== 'server') {
     throw new Error('此入站路由示例需要 HTTP API Server Source');
   }

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

@@ -14,9 +14,8 @@ page 从 1 开始，size 最大 200。summary 只需 uns.stream.view 或 uns.str
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
 
 export async function readStream(id: string, client: Tier0Client = createClient()) {
-  const draft = await client.stream.documents.get({ id });
-  const observation = await client.stream.observations.get({ id });
-  return { draft: draft.data, observation: observation.data };
+  const current = await client.stream.documents.get({ id, view: 'summary' });
+  return { current: current.data };
 }
 export async function* listStreams(client: Tier0Client = createClient()) {
   let page = 1;
@@ -30,6 +29,8 @@ export async function* listStreams(client: Tier0Client = createClient()) {
 }
 ```
 
+查询摘要只需一次请求。编辑完整草稿时显式使用 `documents.get({ id, view: 'full' })`；只看运行观测时直接 `observations.get({ id })`，不先读取草稿。已有写回执时可直接消费其中的状态和修订。
+
 保存、发布、某次执行成功是三个事实。显示实际 revision/activeVersion/release，不用旧 runs 证明新版本生效。版本列表不保证与普通列表相同分页结构；按其 list/total/page/size 读取，versionId 不是 release 序号。
 
 ## 观察本次发布

package/skills/tier0-sdk-v2/tier0-sdk-v2-streams/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: tier0-sdk-v2-streams
-description: "Tier0 App/Stream requests and live business messages: client.streams.requests describe/invoke/discover, client.streams.messages publish/subscribe, trusted App runtime bootstrap and disposable subscriptions. Use for Stream v3 interactions; UNS history, device MQTT and persisted notifications have their own Skills."
+description: "Tier0 App/Stream requests and live business messages: client.streams.requests describe/invoke/discover, client.streams.messages publish/subscribe on a server client with its own key, and disposable subscriptions. Use for Stream v3 interactions; UNS history, device MQTT and persisted notifications have their own Skills."
 ---
 
 # App / Stream Interactions
 
-Read the [root Skill](../SKILL.md) first. These APIs require an artifact built from the unified SDK implementation: pin its commit and SHA-256 until the corresponding version is published.
+Read the [root Skill](../SKILL.md) first.
+
+**In a Tier0 App's server code** the App's key (`TIER0_API_KEY`) can use both. Stream requests and messages are fixed capabilities of every App (`stream.requests.read` / `invoke` / `write`, `stream.messages.publish` / `subscribe`), not configured per App and not approved by an admin. They are still bounded by the workspace plan (a plan without Stream refuses them) and, for requests, by the Stream request grants: the request code must be granted to this App. Message topics come from published Stream manifests: the App may subscribe to a topic a published Stream declares with `api.stream.messages.use({ topic, access: 'publish' })`, and publish to a topic an active Stream subscribes to. There is no per-App topic list. These APIs require an artifact built from the unified SDK implementation: pin its commit and SHA-256 until the corresponding version is published.
 
 ## Select the interaction
 
@@ -16,13 +18,11 @@ Read the [root Skill](../SKILL.md) first. These APIs require an artifact built f
 
 Import `client` or `createClient` from `@tier0/sdk-v2`. The same client exposes `uns`, `source`, `stream`, `capabilities`, `files` and `notifications`. The singular `stream` manages documents, programs and runs; plural `streams` performs App requests and live messaging. MQTT stays in the separate `/mq` entry.
 
-## Trusted App bootstrap
-
-The SWE host installs `globalThis[Symbol.for('tier0.sdk.app-runtime.v1')]` before the App script. The SDK detects it automatically; App business code must not install a replacement provider or resolve credentials itself. The host's provider returns a `Response` for its authenticated request bridge.
+## Server only
 
-Browser App code knows only public request codes, logical topics and business payloads. Do not add broker URLs, physical subjects, API keys, JWTs, nkey seeds, workspace/principal headers or message identity claims to App configuration. `@tier0/sdk-v2/runtime` is a trusted host integration entry point, not App setup.
+Use `client.streams` from server code with a client that holds a key: `createClient()` reads `TIER0_API_HOST` / `TIER0_API_KEY`, or pass `apiHost` / `apiKey`. Never put that key in a browser bundle. Browser code does not call the platform directly; it calls the App's own server routes, which use `client.streams`. There is no browser host bridge.
 
-For a standalone Node service, the deployment supplies its existing HTTP credential and real App context. Call `createClient()` without literals; never put these server credentials in a browser bundle.
+Callers know only public request codes, logical topics and business payloads. Do not add broker URLs, physical subjects, JWTs, nkey seeds, workspace/principal headers or message identity claims to configuration; the SDK obtains a short-lived broker ticket per connection.
 
 ## Public caller
 
@@ -31,12 +31,12 @@ import { createClient, type StreamMessageError } from '@tier0/sdk-v2';
 
 export async function openOrders(
   reportError: (error: StreamMessageError) => void,
-  renderOrderUpdate: (order: { orderId: string }) => void,
+  onOrderUpdate: (order: { orderId: string }) => void,
 ) {
-  const sdk = createClient(); // automatically uses the trusted App runtime
+  const sdk = createClient(); // server: TIER0_API_HOST / TIER0_API_KEY
   const removeErrorHandler = sdk.streams.messages.onError(reportError);
   const subscription = await sdk.streams.messages.use<{ orderId: string }>({ topic: 'orders/accepted' })
-    .subscribe(message => renderOrderUpdate(message.payload));
+    .subscribe(message => onOrderUpdate(message.payload));
   const request = sdk.streams.requests.use<{ orderId: string }, { accepted: boolean }>({ code: 'orders.approve' });
   return {
     describe: () => request.describe(),
@@ -56,9 +56,9 @@ Persist one caller-owned idempotency key per business intent. A deliberate recon
 
 Messages use a versioned `{ version, messageId, correlationId?, payload }` envelope. Caller-supplied identity in a payload is business data, not authenticated publisher metadata; authorized broker subjects establish identity internally.
 
-The SDK uses native Core NATS over WSS, loaded only when messaging starts. Messages require a browser with WebSocket or Node.js 22+; HTTP-only clients remain usable on Node.js 20.19+. Each initial connection, reconnect and renewal gets a new in-memory user key and a public-key-bound JWT. The old socket closes and its private key is wiped before replacement. No private key leaves the SDK. A successful publish means broker flush, not receiver acknowledgement.
+The SDK uses native Core NATS over WSS, loaded only when messaging starts. Messages require Node.js 22+ (WebSocket); HTTP-only clients remain usable on Node.js 20.19+. Each initial connection, reconnect and renewal gets a new in-memory user key and a public-key-bound JWT. The old socket closes and its private key is wiped before replacement. No private key leaves the SDK. A successful publish means broker flush, not receiver acknowledgement.
 
-Register `messages.onError` (or subscription `onError`) to handle asynchronous broker, decoding and handler failures. After an established session disconnects, publish fails immediately: no offline buffering, write retry or message replay. Credential refresh and reconnection restore subscriptions only. Dispose subscriptions and the owned client when the view/service stops.
+Register `messages.onError` (or subscription `onError`) to handle asynchronous broker, decoding and handler failures. After an established session disconnects, publish fails immediately: no offline buffering, write retry or message replay. Credential refresh and reconnection restore subscriptions only. Dispose subscriptions and the owned client when the service stops.
 
 ## Stream-side code
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/SKILL.md

@@ -5,7 +5,7 @@ description: 使用 @tier0/sdk-v2 的 client.uns 完成新架构集合、Schema
 
 # UNS 数据操作
 
-UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本分别用 [Source](../tier0-sdk-v2-source/SKILL.md)、[Stream](../tier0-sdk-v2-stream/SKILL.md)。服务端 `createClient()` 读取 TIER0_API_HOST / TIER0_API_KEY，或显式传 apiHost/apiKey。数据权限不自动授予管理权限：管理操作中 App 凭证只能调用本 App 集合的 appCollectionsEnsure / SchemaReplace / Archive / Restore；appDataPolicyGet/Update 的调用方必须是持有 uns.write 的登录会话、持有 uns.write 且 full_access、不绑定 App 的 personal / agent Key，或治理会话；运行时 App 凭证不能管理数据授权。
+UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本分别用 [Source](../tier0-sdk-v2-source/SKILL.md)、[Stream](../tier0-sdk-v2-stream/SKILL.md)。服务端 `createClient()` 读 TIER0_API_HOST / TIER0_API_KEY（平台里由平台注入 App 的 Key），或显式传 apiHost/apiKey。数据权限不自动授予管理权限：管理操作中 App 凭证只能调用本 App 集合的 appCollectionsEnsure / SchemaReplace / Archive / Restore；appDataPolicyGet/Update 的调用方必须是持有 uns.write 的登录会话、持有 uns.write 且 full_access、不绑定 App 的 personal / agent Key，或治理会话；新增授权（新集合、放宽权限、从 disabled 重新启用）只接受工作区 Owner/Admin 的人工会话或平台导入，其他调用方回 403（reason `app_grant_admin_required` / `app_grant_agent_forbidden`），收窄和移除不受此限；运行时 App 凭证不能管理数据授权。
 
 先按[命名空间指导](references/namespace.md)区分凭证：`namespace()` 走 OpenAPI，但当前不对 App Key 开放；App 查询可用集合走 `dataAppContext`，不能改用同样受限的 `appCollectionsList`。Agent / Personal Key 也须满足当前工作空间权限；不要从“使用 SDK / MCP”推定权限。
 
@@ -19,6 +19,7 @@ UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本
 | 查询集合、筛选/排序记录 | [查询](references/read.md) | dataAppContext、metadataFind/FindOne（非 App 凭证）、collectionDescribe、recordFind |
 | 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、metadataUpdateOne/Many |
 | 删记录、软删除集合 | [删除](references/delete.md) | recordDeleteOne、metadataDeleteOne/Many |
+| 精确删除选中的历史样本 | [删除](references/delete.md#精确删除历史样本) | sampleFind、sampleDeleteExact（非 App 凭证） |
 | 永久删除回收站集合 | [删除](references/delete.md) | metadataPurge、jobs |
 | 恢复集合或记录 | [恢复](references/restore.md) | metadataRestore、recordRestore |
 | 分页、历史采样、事务、写入结果 | [数据工作流](references/data-workflows.md) | sampleFind、recordTransactionExecute |
@@ -46,7 +47,7 @@ export async function readAppRecords(collectionId: string) {
 1. 记录行是 id/data/revision；filter 与 update 的业务路径用 name、customer.name，不加 data.；系统路径用 _id、_meta.revision。
 2. 改/删使用最近写回执或读取取得的 revision 作为 expectedRevision；创建时可用 returnDocument:'after' 取得快照。历史重放不是当前最新版本，冲突时显式处理；不同操作使用独立意图键，长度上限以当前操作契约为准。
 3. metadataUpdateOne 的 $set.recordSchema 替换完整 Schema，不迁移已有记录；未更新的 sampleSchema/indexes 保留。先预检兼容性。
-4. metadataDeleteOne/Many 软删除集合并保留 Record/Sample；metadataPurge 永久清理明确 ID 的回收站集合。accepted 只表示任务已受理，须用 jobs 查询逐项结果。Record 删除会物理删除关联 Sample，恢复 Record 不会恢复这些 Sample。
+4. metadataDeleteOne/Many 软删除保留数据与索引，历史按既有授权只读；目录原子回收有效子树，恢复只覆盖同次批次，详见[回收规则](references/delete.md#回收规则)。metadataPurge 永久清理明确 ID 的回收站集合，accepted 只表示任务已受理，须用 jobs 查询逐项结果。Record 删除会物理删除关联 Sample，恢复 Record 不会恢复这些 Sample。
 5. recordFind 使用 pageInfo.hasMore/nextCursor，limit 1–200；sort 为 [['field',1]]。单页不是全量，跨页不是稳定快照。
 6. Sample 的时间是 Unix 毫秒，查询范围 [from,to)。Record 代表业务实体，不用覆盖它来保存历史。
 

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

@@ -29,8 +29,6 @@ export async function createDeviceCollection(
       },
     },
   };
-  const preview = await client.uns.metadataInsertOne({ ...request, dryRun: true });
-  if (preview.data.status !== 'validated') throw new Error('集合预检未通过');
   const receipt = await client.uns.metadataInsertOne({ ...request, dryRun: false, idempotencyKey: intentKey });
   if (receipt.data.status !== 'committed') return { state: 'unconfirmed' as const, receipt };
   const current = await client.uns.metadataFind({ kind: 'collection', filter: { _id: collectionId }, limit: 1 });
@@ -39,6 +37,8 @@ export async function createDeviceCollection(
 }
 ```
 
+普通创建直接提交，服务端在提交时校验。只有需要展示预检结果时才单独使用 `dryRun: true`，预检不锁定提交条件。示例提交后读取一次，是为了返回服务端补全的集合结构和 revision；仅需创建回执时可省略这次读取。
+
 单条 Record 新增默认返回 insertedId/status/replayed。需要创建后的数据、revision 和时间戳时，传 returnDocument:'after'，同一次写入返回 value，无需再查询；可配合 projection，调用者必须同时具有读取权限。幂等重放返回原始创建快照，后续读取最新状态仍用 recordGet/recordFind。dryRun 的 value 是未提交预览。
 
 returnDocument 只允许 none（默认）或 after，不支持 before；projection 只能和 after 一起传。新增仍是 insert，已存在的 ID 不会变成更新。after 的 value 包括服务端补入的字段，但只返回当前授权可见的数据：普通数据权限需 uns.write 和 uns.read，App 还要满足集合的 record:write / record:read 及当前员工、行和字段策略。服务端在提交前校验读取权限，重放时也重新校验；旧回执不能绕过已撤销的授权。

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

@@ -1,56 +1,83 @@
 # 删除记录与元数据
 
-记录删除仍使用专属数据接口：
+记录删除使用专属数据接口，`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 使用独立的精确清单或显式时间范围删除接口；清理选定样本使用下面的 sampleDeleteExact。
+
+成功回执已确认本次操作，不再固定读回验证。结果未知时保留原意图键，按对象身份核对；需要展示最新状态时再刷新。版本冲突应重新读取并由调用方处理，不自动覆盖。
+
+## 精确删除历史样本
+
+Workspace 管理调用方通过 `client.uns.sampleDeleteExact` 删除当前集合内的明确样本清单，最多 200 条，需要 `uns.delete` 权限；MCP 凭证另需 `uns.write` 授权。运行时 App Key 不支持此操作，也没有对应的 App 数据层方法。
+
+从 `sampleFind` 结果复制 `{recordId,id,time}`，保留原始 Unix 毫秒时间；`id` 不能替代完整身份，`receivedAt` 不能替代 `time`。不接受空清单、重复身份、filter 或时间范围。清理重复样本时，由业务判断哪些样本重复、保留哪条，只把多余项放入清单；接口本身不判断重复，也不改变采集逻辑。
+
+```ts
+import { createClient, type Tier0Client, type UnsV2SampleDeleteExactReq } from '@tier0/sdk-v2';
+
+export async function deleteSelectedSamples(
+  collectionId: string, samples: UnsV2SampleDeleteExactReq['samples'],
+  intentKey: string, dryRun = true, client: Tier0Client = createClient(),
+) {
+  return client.uns.sampleDeleteExact({ collectionId, samples, dryRun, idempotencyKey: intentKey });
+}
+```
 
-业务记录使用 recordDeleteOne/Many，传 collectionId 和明确 filter，编辑型流程同时传 expectedRevision。不要把元数据软删除解释成逐条删除该集合的 Record。Sample 的删除是独立的显式时间范围操作，具体影响遵循当前数据 API 契约。
+`dryRun:true` 仅返回当时的匹配数量，不删除或预留样本。执行时使用同一清单和 `dryRun:false`；省略 dryRun 也会执行。返回 `{deletedCount,missingCount,dryRun}`：deletedCount 在预览时是预计删除数，执行时是实际删除数；missingCount 是未匹配到的完整键数。整批精确删除与回执同事务，不修改父 Record 或未列出的样本。
 
-恢复见[恢复](restore.md)。未知写入结果保留原意图键，先按对象身份核对，不自动换键重试。
+相同执行请求重试复用相同 `idempotencyKey`，修改清单需要新键。SDK 不自动重试；结局未知时按完整键查询核对，遵循错误中的 execution/retry，不改用范围删除或重建集合。`sampleDeleteRange` 仍不向 MCP 开放。
 
 ## 永久删除回收站集合
 

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';
@@ -36,13 +36,10 @@ export async function readAppRecords(alias: string, client: Tier0Client = create
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
 
 export async function readDevices(collectionId: string, client: Tier0Client = createClient()) {
-  const collection = await client.uns.metadataFind({ kind: 'collection', filter: { _id: collectionId }, limit: 1 });
-  const definition = collection.data.items[0];
-  if (!definition) throw new Error('集合不存在或不可见');
   const records = await client.uns.recordFind({
     collectionId, filter: { enabled: true }, sort: [['name', 1]], limit: 20,
   });
-  return { definition: definition.data, items: records.data.items, pageInfo: records.data.pageInfo };
+  return { items: records.data.items, pageInfo: records.data.pageInfo };
 }
 
 export async function listCollections(page = 1, client: Tier0Client = createClient()) {
@@ -54,4 +51,12 @@ 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 时直接读取记录，由服务端校验集合及操作权限；不先调用 metadataFind、dataAppContext、collectionDescribe 或 ensure。需要选择集合或查看结构时，再单独读取对应上下文。
+
+listCollections 的 metadataFind 仅用于 Workspace 集成（会话、personal / agent Key）。App 凭证不能调用 metadataFind；未知 collectionId 时用 dataAppContext 选择已授权集合，集合的 revision、indexStatus、ttl 也在其中。readDevices 只需要目标集合的记录读取权限。网络/权限错误必须传播，不能用空数组掩盖错误。
+
+## 回收集合的历史读取
+
+按原 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，记录恢复可按需查询。

package/dist/cjs/app-identity-contract.generated.d.ts

@@ -1,22 +0,0 @@
-export declare const APP_REQUEST_IDENTITY_CONTRACT: {
-    readonly version: "tier0.app-request-identity/v1";
-    readonly header: "X-Tier0-App-Identity";
-    readonly type: "tier0-app-request+jwt";
-    readonly algorithm: "EdDSA";
-    readonly issuer: "tier0-app-gateway";
-    readonly audience: "tier0-app-runtime";
-    readonly maxTokenBytes: 8192;
-    readonly maxBodyBytes: 65536;
-    readonly maxURIBytes: 8192;
-    readonly maxTTLSeconds: 30;
-    readonly clockSkewSeconds: 5;
-    readonly maxRoles: 32;
-    readonly maxRoleBytes: 128;
-    readonly maxKeys: 8;
-    readonly keyIDPattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$";
-    readonly appIDPattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
-    readonly requiredClaims: readonly ["ver", "iss", "aud", "sub", "workspaceID", "appID", "method", "requestURI", "bodySHA256", "iat", "exp", "jti", "roles"];
-    readonly methodPattern: "^[A-Z]{1,16}$";
-    readonly requiredHeaderFields: readonly ["alg", "typ", "kid"];
-    readonly publicKeyFields: readonly ["kty", "crv", "x", "kid"];
-};