@tier0/sdk-v2 0.9.9 → 0.10.0

package/dist/esm/uns-v2/sse.d.ts

@@ -14,7 +14,13 @@ export interface ServerSentEvent {
 export declare const SSE_MAX_LINE_BYTES: number;
 export declare class ServerSentEventsError extends Error {
 }
-/** Yields each dispatched event and each comment line; `retry:` is ignored. Throws ServerSentEventsError on an oversized line. */
+/**
+ * Yields each dispatched event and each comment line, plus `{ id }` for a frame
+ * that only moves the position; `retry:` is ignored. Throws
+ * ServerSentEventsError on an oversized line.
+ */
 export declare function parseServerSentEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent | {
     comment: string;
+} | {
+    id: string;
 }>;

package/dist/esm/uns-v2/sse.js

@@ -7,7 +7,11 @@
 export const SSE_MAX_LINE_BYTES = 1 << 20;
 export class ServerSentEventsError extends Error {
 }
-/** Yields each dispatched event and each comment line; `retry:` is ignored. Throws ServerSentEventsError on an oversized line. */
+/**
+ * Yields each dispatched event and each comment line, plus `{ id }` for a frame
+ * that only moves the position; `retry:` is ignored. Throws
+ * ServerSentEventsError on an oversized line.
+ */
 export async function* parseServerSentEvents(stream) {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
@@ -15,6 +19,7 @@ export async function* parseServerSentEvents(stream) {
     let event = '';
     let data = [];
     let id;
+    let moved = false;
     try {
         while (true) {
             const { done, value } = await reader.read();
@@ -29,6 +34,9 @@ export async function* parseServerSentEvents(stream) {
                 if (line === '') {
                     if (data.length > 0 || event)
                         yield { event: event || 'message', data: data.join('\n'), ...(id === undefined ? {} : { id }) };
+                    else if (moved && id !== undefined)
+                        yield { id };
+                    moved = false;
                     event = '';
                     data = [];
                     continue;
@@ -45,8 +53,10 @@ export async function* parseServerSentEvents(stream) {
                     event = text;
                 else if (field === 'data')
                     data.push(text);
-                else if (field === 'id' && !text.includes('\u0000'))
+                else if (field === 'id' && !text.includes('\u0000')) {
                     id = text;
+                    moved = true;
+                }
             }
             if (done)
                 return;

package/dist/esm/uns-v2/sse.js.map

@@ -1 +1 @@
-{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../../src/uns-v2/sse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Minimal `text/event-stream` parser (WHATWG server-sent events). Unlike\n * EventSource it also dispatches a named event without data lines, and\n * reports comment lines, so a keep-alive in either form is visible.\n */\n\nexport interface ServerSentEvent {\n  /** `message` when the server names no event. */\n  event: string;\n  data: string;\n  /** Last `id:` seen on the stream so far, as EventSource keeps it. */\n  id?: string;\n}\n\n/** A line longer than this is not an event stream (e.g. a proxy page without newlines). */\nexport const SSE_MAX_LINE_BYTES = 1 << 20;\n\nexport class ServerSentEventsError extends Error {}\n\n/** Yields each dispatched event and each comment line; `retry:` is ignored. Throws ServerSentEventsError on an oversized line. */\nexport async function* parseServerSentEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent | { comment: string }> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '';\n  let event = '';\n  let data: string[] = [];\n  let id: string | undefined;\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });\n      // A trailing \"\\r\" may be the first half of \"\\r\\n\": keep it for the next chunk.\n      const lines = buffer.split(/\\r\\n|\\n|\\r(?!$)/);\n      buffer = done ? '' : (lines.pop() ?? '');\n      // UTF-16 length bounds the UTF-8 size from below; good enough to stop runaway input.\n      if (buffer.length > SSE_MAX_LINE_BYTES) throw new ServerSentEventsError('Server-sent event line too long.');\n      for (const line of lines) {\n        if (line === '') {\n          if (data.length > 0 || event) yield { event: event || 'message', data: data.join('\\n'), ...(id === undefined ? {} : { id }) };\n          event = '';\n          data = [];\n          continue;\n        }\n        if (line.startsWith(':')) {\n          yield { comment: line.slice(1).trimStart() };\n          continue;\n        }\n        const colon = line.indexOf(':');\n        const field = colon < 0 ? line : line.slice(0, colon);\n        const raw = colon < 0 ? '' : line.slice(colon + 1);\n        const text = raw.startsWith(' ') ? raw.slice(1) : raw;\n        if (field === 'event') event = text;\n        else if (field === 'data') data.push(text);\n        else if (field === 'id' && !text.includes('\\u0000')) id = text;\n      }\n      if (done) return;\n    }\n  } finally {\n    await reader.cancel().catch(() => undefined);\n    reader.releaseLock();\n  }\n}\n"]}
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../../src/uns-v2/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,CAAC;AAE1C,MAAM,OAAO,qBAAsB,SAAQ,KAAK;CAAG;AAEnD;;;;GAIG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,qBAAqB,CAAC,MAAkC;IAC7E,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,IAAI,GAAa,EAAE,CAAC;IACxB,IAAI,EAAsB,CAAC;IAC3B,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,+EAA+E;YAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YAC9C,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,qFAAqF;YACrF,IAAI,MAAM,CAAC,MAAM,GAAG,kBAAkB;gBAAE,MAAM,IAAI,qBAAqB,CAAC,kCAAkC,CAAC,CAAC;YAC5G,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;oBAChB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK;wBAAE,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;yBACzH,IAAI,KAAK,IAAI,EAAE,KAAK,SAAS;wBAAE,MAAM,EAAE,EAAE,EAAE,CAAC;oBACjD,KAAK,GAAG,KAAK,CAAC;oBACd,KAAK,GAAG,EAAE,CAAC;oBACX,IAAI,GAAG,EAAE,CAAC;oBACV,SAAS;gBACX,CAAC;gBACD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;oBAC7C,SAAS;gBACX,CAAC;gBACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAChC,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;gBACtD,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;gBACnD,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;gBACtD,IAAI,KAAK,KAAK,OAAO;oBAAE,KAAK,GAAG,IAAI,CAAC;qBAC/B,IAAI,KAAK,KAAK,MAAM;oBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;qBACtC,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACpD,EAAE,GAAG,IAAI,CAAC;oBACV,KAAK,GAAG,IAAI,CAAC;gBACf,CAAC;YACH,CAAC;YACD,IAAI,IAAI;gBAAE,OAAO;QACnB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;AACH,CAAC","sourcesContent":["/**\n * Minimal `text/event-stream` parser (WHATWG server-sent events). Unlike\n * EventSource it also dispatches a named event without data lines, and\n * reports comment lines, so a keep-alive in either form is visible.\n */\n\nexport interface ServerSentEvent {\n  /** `message` when the server names no event. */\n  event: string;\n  data: string;\n  /** Last `id:` seen on the stream so far, as EventSource keeps it. */\n  id?: string;\n}\n\n/** A line longer than this is not an event stream (e.g. a proxy page without newlines). */\nexport const SSE_MAX_LINE_BYTES = 1 << 20;\n\nexport class ServerSentEventsError extends Error {}\n\n/**\n * Yields each dispatched event and each comment line, plus `{ id }` for a frame\n * that only moves the position; `retry:` is ignored. Throws\n * ServerSentEventsError on an oversized line.\n */\nexport async function* parseServerSentEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent | { comment: string } | { id: string }> {\n  const reader = stream.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '';\n  let event = '';\n  let data: string[] = [];\n  let id: string | undefined;\n  let moved = false;\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });\n      // A trailing \"\\r\" may be the first half of \"\\r\\n\": keep it for the next chunk.\n      const lines = buffer.split(/\\r\\n|\\n|\\r(?!$)/);\n      buffer = done ? '' : (lines.pop() ?? '');\n      // UTF-16 length bounds the UTF-8 size from below; good enough to stop runaway input.\n      if (buffer.length > SSE_MAX_LINE_BYTES) throw new ServerSentEventsError('Server-sent event line too long.');\n      for (const line of lines) {\n        if (line === '') {\n          if (data.length > 0 || event) yield { event: event || 'message', data: data.join('\\n'), ...(id === undefined ? {} : { id }) };\n          else if (moved && id !== undefined) yield { id };\n          moved = false;\n          event = '';\n          data = [];\n          continue;\n        }\n        if (line.startsWith(':')) {\n          yield { comment: line.slice(1).trimStart() };\n          continue;\n        }\n        const colon = line.indexOf(':');\n        const field = colon < 0 ? line : line.slice(0, colon);\n        const raw = colon < 0 ? '' : line.slice(colon + 1);\n        const text = raw.startsWith(' ') ? raw.slice(1) : raw;\n        if (field === 'event') event = text;\n        else if (field === 'data') data.push(text);\n        else if (field === 'id' && !text.includes('\\u0000')) {\n          id = text;\n          moved = true;\n        }\n      }\n      if (done) return;\n    }\n  } finally {\n    await reader.cancel().catch(() => undefined);\n    reader.releaseLock();\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.9.9",
+  "version": "0.10.0",
   "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
   "license": "MIT",
   "type": "module",
@@ -97,6 +97,26 @@
         "default": "./dist/cjs/mq/index.js"
       }
     },
+    "./page-runtime": {
+      "import": {
+        "types": "./dist/esm/page-runtime.d.ts",
+        "default": "./dist/esm/page-runtime.js"
+      },
+      "require": {
+        "types": "./dist/cjs/page-runtime.d.ts",
+        "default": "./dist/cjs/page-runtime.js"
+      }
+    },
+    "./event-stream": {
+      "import": {
+        "types": "./dist/esm/event-stream.d.ts",
+        "default": "./dist/esm/event-stream.js"
+      },
+      "require": {
+        "types": "./dist/cjs/event-stream.d.ts",
+        "default": "./dist/cjs/event-stream.js"
+      }
+    },
     "./server": {
       "import": {
         "types": "./dist/esm/cloud-server.d.ts",
@@ -152,16 +172,6 @@
       }
     },
     "./package.json": "./package.json",
-    "./runtime": {
-      "import": {
-        "types": "./dist/esm/runtime.d.ts",
-        "default": "./dist/esm/runtime.js"
-      },
-      "require": {
-        "types": "./dist/cjs/runtime.d.ts",
-        "default": "./dist/cjs/runtime.js"
-      }
-    },
     "./streams": {
       "import": {
         "types": "./dist/esm/streams/index.d.ts",
@@ -175,13 +185,15 @@
   },
   "scripts": {
     "sync:contracts": "node scripts/sync-contracts.mjs",
+    "sync:source-stream-contract": "node scripts/sync-source-stream-contract.mjs",
     "generate": "node scripts/generate-openapi.mjs && node scripts/generate-uns-v2.mjs",
-    "check:contracts": "node scripts/check-contracts.mjs && npm run check:acquisition-contract && node scripts/sync-capability-contract.mjs --check && node --test scripts/retired-stream-probe.test.mjs scripts/retired-http-push.test.mjs scripts/retired-controls.test.mjs scripts/retired-public-labels.test.mjs scripts/platform-schema-projection.test.mjs scripts/data-capability-vector.test.mjs scripts/sync-contracts.test.mjs scripts/sync-capability-contract.test.mjs scripts/live-program-contract.test.mjs scripts/sync-http-run-observations.test.mjs && node scripts/generate-openapi.mjs --check && node scripts/generate-uns-v2.mjs --check && npm run check:stream-contract",
+    "check:contracts": "node scripts/check-contracts.mjs && npm run check:acquisition-contract && node scripts/sync-capability-contract.mjs --check && node --test scripts/retired-stream-probe.test.mjs scripts/retired-http-push.test.mjs scripts/retired-controls.test.mjs scripts/retired-public-labels.test.mjs scripts/platform-schema-projection.test.mjs scripts/data-capability-vector.test.mjs scripts/sync-contracts.test.mjs scripts/sync-capability-contract.test.mjs scripts/live-program-contract.test.mjs scripts/sync-http-run-observations.test.mjs scripts/member-list-proxy-guidance.test.mjs && node scripts/generate-openapi.mjs --check && node scripts/generate-uns-v2.mjs --check && npm run check:stream-contract",
     "check:skills": "node scripts/check-skills.mjs && node scripts/check-skill-examples.mjs",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "build": "node scripts/build.mjs",
     "prepare": "npm run build",
     "test": "vitest run",
+    "test:gateway-enforce": "node scripts/test-gateway-enforce.mjs",
     "check": "npm run check:contracts && npm run check:skills && npm run typecheck && npm test && npm run build && node scripts/check-package.mjs",
     "prepack": "node scripts/sync-stream-contract.mjs --check --committed && node scripts/check-contracts.mjs --committed && npm run check:contracts && npm run check:skills && npm run build",
     "prepublishOnly": "node scripts/sync-stream-contract.mjs --check --committed && node scripts/check-contracts.mjs --committed && npm run check",
@@ -226,6 +238,7 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "esbuild": "^0.25.0",
+    "mqtt-v530": "npm:mqtt@5.3.0",
     "openapi-typescript": "^7.0.0",
     "react": "^19.0.0",
     "typescript": "~5.9.3",

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

@@ -27,19 +27,27 @@ description: 使用 @tier0/sdk-v2 开发或迁移 Tier0 云端 TypeScript/JavaSc
 
 ## 初始化与身份
 
+个人 Key 可直接读取已有集合，无需创建平台 App；网关配置、运行示例与排错见[本地连接指南](references/local-connection.md)。
+
 ```ts
 import { createClient } from '@tier0/sdk-v2';
 
-// 服务端注入 TIER0_API_HOST / TIER0_API_KEY。
+// 平台注入 TIER0_API_HOST 和 App 的 Key TIER0_API_KEY；本地开发自己设这两个。
 export const client = createClient({ transportTimeoutMs: 30_000 });
 export async function inspectConnection() {
   return client.system.info();
 }
 ```
 
-也可传 `apiHost`、`apiKey` 或 `getApiHost` / `getApiKey` 回调。API Key 留在服务端；不要生成 `VITE_*KEY` 或让页面携带 App Key。浏览器通过自己的服务端接口访问平台；App Stream 交互使用根入口 `client` 和受信宿主注入，无需设置密钥。消息要求 WebSocket（Node.js 22+ 或浏览器）。
+也可传 `apiHost`、`apiKey` 或 `getApiHost` / `getApiKey` 回调。API Key 留在服务端；不要生成 `VITE_*KEY` 或让页面携带 App Key。浏览器通过自己的服务端接口访问平台；App Stream 交互（`client.streams`）也只在服务端用带 Key 的客户端。消息要求 Node.js 22+（WebSocket）。
+
+凭证来源按属性存在性选择，优先顺序为 `apiKeyProvider`、`apiKey`、`getApiKey`；只有都未提供才读取 `TIER0_API_KEY`。显式 `undefined` 或 getter 返回 `undefined` 不会回退到环境 Key。每个用户请求使用独立客户端，不要把全局 `configureClient` 当作请求身份。
+
+**Tier0 预览和部署里，App 的 Key 在运行进程的环境里**：平台注入 `TIER0_API_KEY`（这个 App 的 Key，秘密；预览是 preview Key，部署是 deployed Key）和 `TIER0_API_HOST`，`createClient()` 直接用它们，只发一个 `X-API-Key`。App 代码不要自己读、复制、打印或下发这个 Key，也不要生成或硬编码 Key；直接调平台时也通过 SDK。身份读平台设置的 `TIER0_WORKSPACE_ID`、`TIER0_APP_ID`。
+
+App 的 Key 只能调 `/openapi/v2/uns/**`、`assets/files/**`（`client.files`；`assets/upload` 不在内）、`notifications/send`、`platform/getMembers`（`members.listWorkspace()`）、`apps/access-members/list`（`members.listApp()`）、`stream-requests/discover` 和 `stream-requests/<code>/describe|invoke`、`stream-messages/connect`（`client.streams`）、`capabilities/discover`、`info`；其他接口（`system.whoami()`、`notifications.get`、`mqttAuth`、`agent`）回 403 `hosted_app_key_route_forbidden`；Source / Stream 管理接口 App 的 Key 无权调用，Backend 回 403。App 的平台能力固定 11 项（`openapi.base`、`platform.users.read`、`notifications.send`、文件上传 / 下载 / 删除、`stream.requests.read` / `invoke` / `write`、`stream.messages.publish` / `subscribe`），每个 App 都有、不在 App 设置里配置，生效的是它们和 Key 权限、Key 模式、工作区套餐的交集。外部集合只由工作区 Owner/Admin 在 App 设置里授权，删掉后下一个请求起生效。MQTT 主题只能用 App 自己的命名空间 `apps/<TIER0_APP_ID>/<TIER0_RUNTIME>/…`，用 `appTopic()` 拼，见 [MQTT](tier0-sdk-v2-mq/SKILL.md)。没有 `TIER0_API_KEY` 而 `TIER0_RUNTIME` 为 `deployed` / `preview` 时 SDK 进入平台代理模式（不发凭据、带 `X-Tier0-SDK: 1`），当前平台不会出现这种运行时，见 [错误码](tier0-sdk-v2-data/references/errors.md#平台代理模式的错误)。
 
-不同身份使用独立实例。含员工数据委托时，每个入站请求新建实例，使用受信 App Gateway 提供的 `unsV2AppDataSubject`；它不是用户 ID，也不是 App 请求验签断言。不要从请求 JSON 拼造委托。身份验签流程见 [身份与框架集成](references/integration.md)。
+不同身份使用独立实例。App 调平台只有一种身份：App 自身。当前用户和角色从前门注入的 `X-Tier0-Visitor` 读（`parseVisitorHeader`），按角色决定谁能看、能改什么由 App 在服务端自己做，见 [身份与框架集成](references/integration.md)。
 
 ## 返回值与错误
 
@@ -52,7 +60,7 @@ export async function inspectConnection() {
 
 方法存在不等于目标环境已部署或当前 Key 有权限。整数可能为 `bigint`；UNS 任意 JSON 中还可能含 `UnsV2RawNumber`。不要将标识符强制转为 Number；给浏览器返回数据时显式定义精确数字的序列化格式。
 
-`createClient()` 的 HTTP 不自动重试。UNS 错误的 `execution` 说明执行到哪一步、`retry.safe` 说明能否用同一请求重发；带 `outcomeUnknown` 的失败应先对账，保留原意图键；取消请求不代表服务端撤销。App 数据层（`@tier0/sdk-v2/data`）会按 `retry.safe` 自动重试，见 App 数据 Skill。Source/Stream 仍使用底层 UNS v2 契约，所以错误类名保留 UNS，不代表它们仍属于数据入口。
+`createClient()` 的 HTTP 不自动重试，唯一例外是平台代理模式下代理自己产生的 `503` / `429`（带 `X-Tier0-Proxy: not-forwarded`，请求没有到达平台），SDK 按 `retry_after_ms` 最多重试 3 次；平台返回的 5xx 不重试。UNS 错误的 `execution` 说明执行到哪一步、`retry.safe` 说明能否用同一请求重发；带 `outcomeUnknown` 的失败应先对账，保留原意图键；取消请求不代表服务端撤销。App 数据层（`@tier0/sdk-v2/data`）会按 `retry.safe` 自动重试，见 App 数据 Skill。Source/Stream 仍使用底层 UNS v2 契约，所以错误类名保留 UNS，不代表它们仍属于数据入口。
 
 ## 从首版入口迁移
 
@@ -63,7 +71,7 @@ export async function inspectConnection() {
 - `client.uns.recordFind(body)` 保持不变。
 - 低层 `createUnsV2Client` 保留完整生成契约，供契约工具使用；业务主入口不再把 Source/Stream 管理混入 `client.uns`。
 
-React/Vue 示例与验签见 [集成参考](references/integration.md)。完成接入时验证目标入口、真实身份、响应解包和错误分支；SDK 本地测试通过不代表环境联调完成。
+访问者身份与 React/Vue 示例见 [集成参考](references/integration.md)。完成接入时验证目标入口、真实身份、响应解包和错误分支；SDK 本地测试通过不代表环境联调完成。
 
 Stream 请求与消息交互统一使用本包 `client.streams.requests` / `client.streams.messages`；[交互说明](tier0-sdk-v2-streams/SKILL.md)。Scaffold 只依赖本包；`client.stream` 管理接口与运行时交互用途不同。
 

package/skills/tier0-sdk-v2/references/integration.md

@@ -2,36 +2,26 @@
 
 仅在接入服务端身份或 React/Vue 时阅读本文件。基本分域调用见入口 Skill。
 
-## 网关身份验签
+## 访问者身份（X-Tier0-Visitor）
 
-使用服务端入口，公钥与期望 appID/workspaceID 来自固定服务端配置，不能从请求的 JWK/URL 取钥。保留原始请求字节与路径+query；JSON 解析、重编码或路径归一化后再验签会破坏绑定。
+平台里 App 的每个请求都经过前门：前门先剥掉客户端带来的全部 `X-Tier0-*`，再注入明文的 `X-Tier0-Visitor`（UTF-8 JSON 对象的无填充 base64url，不签名）。服务端用 `parseVisitorHeader` 解析，它严格校验字段、类型、长度，并要求 `app` 等于 `TIER0_APP_ID`：
 
 ```ts
-import {
-  createCloudAppRequestVerifier,
-  type CloudAppIdentityAuthority,
-  type CloudAppIdentityRequest,
-} from '@tier0/sdk-v2/server';
-
-export function authenticateRequest(authority: CloudAppIdentityAuthority, request: CloudAppIdentityRequest) {
-  const verify = createCloudAppRequestVerifier(authority);
-  return verify(request);
+import { parseVisitorHeader, VISITOR_HEADER, VisitorError, type Visitor } from '@tier0/sdk-v2/server';
+
+export function visitorOf(request: Request): Visitor | null {
+  try {
+    return parseVisitorHeader(request.headers.get(VISITOR_HEADER));
+  } catch (error) {
+    if (error instanceof VisitorError && error.code === 'VISITOR_HEADER_INVALID') return null; // 回 401
+    throw error; // VISITOR_CONFIGURATION_INVALID：没有 TIER0_APP_ID，回 503
+  }
 }
 ```
 
-输入 assertion 对应平台约定的 APP_REQUEST_IDENTITY_HEADER；method、requestURI、body 必须是网关签名对应的值。成功只证明该请求来源与员工身份，业务授权仍单独检查。失败拒绝当前请求，不从未验证 claims 兜底建立身份。
+返回 `{ subType: 'employee' | 'machine', subject, grant, workspaceID, appID, runtime: 'deployed' | 'preview', appRoles, activeRole? }`。`appRoles` 是访问者在 App 里的角色（预览里是「以某角色查看」选中的角色），`activeRole` 只在预览的「以某角色查看」里出现，只用于展示。
 
-App 请求断言与 UNS 员工数据委托是不同的 audience。只有受信接入层获得真实 App-Data-Subject 后，才能为本次请求创建客户端：
-
-```ts
-import { createClient } from '@tier0/sdk-v2';
-
-export function clientForTrustedGatewayRequest(apiHost: string, apiKey: string, trustedDataSubject: string) {
-  return createClient({ apiHost, apiKey, unsV2AppDataSubject: trustedDataSubject });
-}
-```
-
-SDK 仅检查委托的紧凑格式，不自行信任/验证其 claims。不要直接转发公开入口任意同名 header，部署边界必须保证它来自可信网关。不要跨员工复用这个实例或令牌。
+App 调平台只有一种身份：App 自身（App Key，平台注入在运行进程的 `TIER0_API_KEY` 里，SDK 直接用）。平台不按访问者收窄 App 的数据，按角色决定当前用户能看、能改哪些记录是 App 自己的事：在服务端按 `appRoles` 过滤查询条件、拒绝写入，返回给浏览器前裁掉不该看的字段。不要把访问者 ID 或角色当成平台调用的参数去「代表」用户。
 
 ## React
 
@@ -69,4 +59,4 @@ export function useRecords(client: Tier0Client) {
 
 ## 联调证据
 
-本 SDK 验签契约沿用已记录的上游 App 网关契约，须与目标环境实际注入的 header/公钥/受众对照。契约生成、类型与本地测试证明包内部一致，不替代环境联调。确认身份、权限与字段返回后再切换真实业务流量。
+访问者头的字段以平台前门实际注入的 `X-Tier0-Visitor` 为准。契约生成、类型与本地测试证明包内部一致，不替代环境联调。确认身份、权限与字段返回后再切换真实业务流量。

package/skills/tier0-sdk-v2/references/local-connection.md

@@ -0,0 +1,61 @@
+# 本地连接与排错
+
+个人 Key 可用于本地脚本、数据分析和调试。SDK 与 MCP 是两种调用入口；MCP 已连接不代表本地 SDK 已配置地址或凭证。读取已有普通 collection 不要求创建或部署平台 App，也不需要 App ID。实际访问范围由个人 Key 及其所属用户的权限决定。
+
+## 确定 API 地址
+
+`apiHost` / `TIER0_API_HOST` 填写当前环境的 **OpenAPI 网关基础地址**，不附加 `/openapi/v2`、页面路径或 Workspace ID；SDK 自动添加接口路径。平台网页地址、MCP 地址与网关地址不能互换。
+
+| 已知平台环境 | OpenAPI 网关基础地址 |
+| --- | --- |
+| 阿里云 ACK 开发环境 `https://dev.tier0.cn` | `https://api-dev.tier0.cn` |
+
+其他环境或私有化部署：从该环境的部署/接入指南取得 OpenAPI 公网入口；若指南未提供，向环境管理员确认“对本机可达、暴露 `/openapi/v2` 的网关基础地址”。不要靠网页域名拼接或猜测地址。若没有对外暴露网关，需由管理员提供入口或网络接入方式，SDK 无法补齐部署。
+
+私有化地址通过 `apiHost` 或环境变量显式配置，支持已有的基础路径前缀。本地 HTTP 网关需写明 `http://`，裸域名默认 HTTPS。SDK 不从 Key 推断地址，不探测候选域名、不自动切换 Host，也不跟随 API 重定向传递密钥。
+
+## 个人 Key 读取已有集合
+
+安装 SDK，使用 Node.js 20.19+。在本机创建 `.env.local`，将它加入 `.gitignore`，填入已经确认的网关、个人 Key 和 collection ID。密钥只留在本地受控配置或服务端，不写进代码、浏览器变量、日志或提交记录。
+
+```dotenv
+TIER0_API_HOST=https://api-dev.tier0.cn
+TIER0_API_KEY=填入该环境的个人Key
+TIER0_COLLECTION_ID=填入已有collection的ID
+```
+
+将以下代码保存为 `read-records.mjs`，按已知集合 ID 直接读取。
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+const collectionId = process.env.TIER0_COLLECTION_ID;
+if (!collectionId) throw new Error('请设置 TIER0_COLLECTION_ID');
+const client = createClient();
+const result = await client.uns.recordFind({ collectionId, limit: 20 });
+console.dir(result.data, { depth: null });
+```
+
+```sh
+node --env-file=.env.local read-records.mjs
+```
+
+示例只读第一页，后续按 `pageInfo` 分页；不会创建集合、修改 Schema 或写入种子数据。collection 由 MCP、页面或其他应用创建不影响此调用方式，知道 ID 不代表取得权限。长期团队应用使用独立 App 身份，避免依赖某个员工的个人 Key。
+
+个人 Key 也可通过数据层的 `data.collection({ collectionId })` 引用已有集合、跳过 ensure（见[已有集合用法](../tier0-sdk-v2-data/references/modeling.md)）；`defineCollection` 声明集合的自动 ensure 需要平台签发的 App Key。
+
+## 按响应排错
+
+| 响应或错误 | 下一步 |
+| --- | --- |
+| HTML / 非 JSON 404、405 | 核对网关基础地址及 `/openapi/v2` 路由；不要先更换 Key。网页域名可能只提供前端页面。 |
+| 401 | 先确认目标网关，再检查 Key 是否提供、是否有效、是否属于该环境；网关前的代理也可能要求认证。 |
+| 403 | 检查当前凭证的资源/操作权限与网关访问限制；不等同于 Key 无效。 |
+| 502、503、504 | 检查网关和上游服务健康；重发写入前确认执行结果，避免重复写入。 |
+| 200 但返回 HTML / `SDK_PROTOCOL` | 核对网关地址、代理转发及响应格式；页面可打开不代表 OpenAPI 可用。 |
+| 网络错误或超时 | 检查 DNS、网络接入、TLS 和服务连通性；不能仅据此判断凭证无效。 |
+| 正常 JSON 业务错误 | 按服务端错误码、权限信息和请求 ID 排查；JSON 404 也可能表示业务资源不存在。 |
+
+身份或 Workspace 不明确时，可单独调用 `client.system.whoami()` 核对返回的 `workspaceID`；它不是读取记录的前置步骤。无密钥请求返回 401 只证明已到达认证入口，不能证明某个 Key 有权读取目标集合。
+
+错误提示不回显 Key、配置 URL 或原始 HTML；SDK 保留原有错误类型、HTTP 状态和执行/重试语义，不自动更换凭证或重试。

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

@@ -1,6 +1,6 @@
 ---
 name: tier0-sdk-v2-data
-description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App 的 UNS 集合：Zod 建模、种子与 TTL、Mongo 风格读写、带总数分页与分组计数、原子批量与事务、变更订阅、员工数据主体、Schema 演进和错误码处理。
+description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App 的 UNS 集合：Zod 建模、种子与 TTL、Mongo 风格读写、带总数分页与分组计数、原子批量与事务、变更订阅与转发给浏览器、Schema 演进和错误码处理。
 ---
 
 # App 数据层
@@ -9,9 +9,15 @@ description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App
 
 `@tier0/sdk-v2/data` 是 App 业务数据的服务端入口：用 `defineCollection` 声明集合，`createDataClient` 在首次访问时一次性 ensure 全部声明，然后用 Mongo 驱动风格的集合句柄读写 UNS 记录。没有 SQL、ORM、连接串或迁移步骤；Preview 与部署后的 App 共用同一批集合和记录。
 
+所有数据调用都是 App 自身：平台不按当前用户收窄。按用户角色决定谁能看、能改哪些记录由 App 在服务端自己做，当前用户和角色从访问者头读（`@tier0/sdk-v2/server` 的 `parseVisitorHeader`，见[身份与框架集成](../references/integration.md)）。
+
 这里创建的集合以 `ownerAppId` 标识唯一所属 App。使用已有或其他 App 共享的集合时，用 `data.collection({ collectionId })` 获取句柄；可选 `schema` 仅做本地写入校验，不创建或修改集合。已有 ID 引用同样用于 `queryBatch`、`transact` 和 `subscribe`，不放入 `createDataClient` 的 `collections` 声明数组，不执行 ensure 或写种子。无需服务端 alias，仍须当前 App 已有相应集合授权；SDK 不授予权限，复用不改变所属关系。底层 [UNS](../tier0-sdk-v2-uns/SKILL.md) 的记录接口仍可直接按 ID 使用。
 
-数据读写只在服务端代码（业务 service）里用 `@tier0/sdk-v2/data`：该入口依赖 Node 内置模块，浏览器打包会直接失败。组件和 route 的客户端代码只能从 `@tier0/sdk-v2/data/define` 取集合声明和类型（`defineCollection`、`Doc`、`NewDoc` 等），它不加载数据运行时，可以进浏览器包。需要 `zod` 4。底层调用 SDK 生成的 UNS 操作（`appCollectionsEnsure`、`recordFind`、`recordTransactionExecute` 等），凭证读取平台注入的 TIER0_API_HOST / TIER0_API_KEY。
+数据读写只在服务端代码（业务 service）里用 `@tier0/sdk-v2/data`：该入口依赖 Node 内置模块，浏览器打包会直接失败。组件和 route 的客户端代码只能从 `@tier0/sdk-v2/data/define` 取集合声明和类型（`defineCollection`、`Doc`、`NewDoc` 等），它不加载数据运行时，可以进浏览器包。需要 `zod` 4。底层调用 SDK 生成的 UNS 操作（`appCollectionsEnsure`、`recordFind`、`recordTransactionExecute` 等），Tier0 预览和部署里读平台注入的 TIER0_API_HOST 和 App 的 Key TIER0_API_KEY（种子在 ensure 时以 App 身份写入）；本地开发自己设这两个。
+
+Data 客户端创建时固定 Host 和 Key（含环境值），不支持 `getApiKey` 或 `apiKeyProvider`；切换身份、Host 或环境凭证时须新建客户端，不能让 bootstrap、重试或订阅状态跨身份复用。
+
+服务端已从可信身份链取得某主体的有效 Key 时，可用 `createDataClient({ apiHost, apiKey })` 为该主体创建独立实例，通过 `collection({ collectionId })` 访问其已获授权的现有集合；不要跨主体共享该实例。Key 轮换后创建新实例。声明集合的 ensure/seed 仍由服务端判断凭证是否有权限，不因创建客户端而获得授权。
 
 集合声明必须分别填写业务名称 `name` 与稳定程序标识 `alias`，例如 `name: '生产工单'`、`alias: 'production_orders'`。name 是唯一界面名称，没有 displayName 或 alias 回退；ensure 通过 alias 找回原集合，不覆盖用户改名。
 
@@ -20,14 +26,14 @@ description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App
 | 用户任务 | 参考 |
 | --- | --- |
 | 声明集合、选字段类型、索引、种子数据、文档建模 | [建模](references/modeling.md) |
-| 查询、按 ID 读取、一页一次请求（queryBatch）、分页、聚合、写入、批量与原子性、订阅变更 | [读写](references/read-write.md) |
-| 状态流转、并发编辑、跨文档不变量、计数器、员工身份与后台任务 | [一致性与身份](references/consistency.md) |
+| 查询、按 ID 读取、一页一次请求（queryBatch）、分页、聚合、写入、批量与原子性、订阅变更并转发给浏览器 | [读写](references/read-write.md) |
+| 状态流转、并发编辑、跨文档不变量、计数器、请求中止与后台任务 | [一致性与请求上下文](references/consistency.md) |
 | 加字段、改类型、改描述、收窄 Schema | [Schema 演进](references/schema-evolution.md) |
 | DataError 字段、UNS 错误码与处理 | [错误码](references/errors.md) |
 
 ## 最小用法
 
-新 App 没有集合时是正常空态：`uns.dataAppContext({})` 返回 `dataState: "uninitialized"` 和空集合，不创建任何数据。无需先调用 context 或手工激活数据策略；声明真实业务集合后，第一次数据访问会自动初始化。`dataState: "ready"` 也不代表可访问整个工作空间，仍以返回的集合授权为准。引用已有 WMS 等集合需要明确共享授权，不能创建同名空集合代替。管理员停用返回 `FORBIDDEN`、reason `APP_DATA_POLICY_DISABLED`，不得自动恢复。
+新 App 没有集合时是正常空态：`uns.dataAppContext({})` 返回 `dataState: "uninitialized"` 和空集合，不创建任何数据。无需先调用 context 或手工激活数据策略；声明真实业务集合后，第一次数据访问会自动初始化。`dataState: "ready"` 也不代表可访问整个工作空间，仍以返回的集合授权为准。引用已有 WMS 等外部集合要由工作区 Owner/Admin 在 App 设置里授权（Builder agent 加不了），不能创建同名空集合代替；授权删掉后下一个请求起被拒绝。管理员停用返回 `FORBIDDEN`、reason `APP_DATA_POLICY_DISABLED`，不得自动恢复。
 
 ```ts
 import { z } from 'zod';

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/consistency.md

@@ -39,32 +39,28 @@ export async function nextOrderNumber() {
 
 `transact` 的结果状态不是 `committed`（`dryRun` 时为 `validated`）会抛 `TRANSACTION_FAILED`，`details.results` 带每一步的错误。
 
-## 调用身份
+## 调用身份与请求上下文
 
-每次调用都使用平台注入的 App Key。处理业务请求时，数据层还会转发网关签发的员工断言（`X-Tier0-App-Data-Subject`），让 UNS 的数据规则与记录租约作用于该员工。集合 ensure 与种子写入以 App 身份执行。
+每次调用都是 App 自身，使用平台注入的 App Key；集合 ensure、种子写入、记录租约、幂等键都只按 App 区分，不按当前用户区分。按用户角色决定谁能看、能改什么由 App 在服务端自己做（当前用户和角色见[身份与框架集成](../../references/integration.md)的访问者头）。
 
-App 的请求入口用 `runWithRequestContext(request, next)` 打开请求上下文（传 `Request` 本身：调用方断开时，还在排队的数据调用不再发出，进行中的被取消；只传 `request.headers` 则没有取消）；脱离请求的工作（定时器、队列、发出即不管的后续任务）放进 `runAsApp(() => ...)`，这些调用不带员工身份；员工身份下取得的租约不能由这类 App 级工作释放。断言格式由 SDK 校验（三段 base64url），格式不合法时调用在发出请求前失败。
+请求入口用 `runWithAbortSignal(request.signal, next)` 把请求的中止信号交给数据层：调用方断开时，这个请求还在排队的数据调用不再发出（`DATA_ABORTED`，`notStarted`），进行中的被取消。脱离请求的工作（定时器、队列、发出即不管的后续任务）放进 `runDetached(() => ...)`，不随请求中止。ensure、种子写入和 `data.subscribe` 本来就不受请求中止影响。
 
 ```ts
-import { currentDataSubject, runAsApp, runWithRequestContext } from '@tier0/sdk-v2/data';
+import { runDetached, runWithAbortSignal } from '@tier0/sdk-v2/data';
 
 export function handleRequest<T>(request: Request, next: () => Promise<T>): Promise<T> {
-  return runWithRequestContext(request, next);
+  return runWithAbortSignal(request.signal, next);
 }
 
 export function scheduleFollowUp(task: () => Promise<void>) {
-  setTimeout(() => void runAsApp(task), 1000);
-}
-
-export function servingEmployee(): boolean {
-  return currentDataSubject() !== undefined;
+  setTimeout(() => void runDetached(task), 1000);
 }
 ```
 
 ## 首次访问与自愈
 
-进程内第一次数据访问会一次性 ensure 全部声明：缺失的集合会被创建（随后写入种子），更宽的声明会放宽存储，存储永远不会被收窄。ensure 失败不缓存，下一次请求会重试（刚导入的 App 可能短暂返回 `APP_NOT_READY`，数据层先自动重试，仍失败时按 503 回答）。
+进程内第一次访问声明集合时一次性 ensure 全部声明：缺失的集合会被创建（随后写入种子），更宽的声明会放宽存储，存储永远不会被收窄。ensure 失败不缓存，下一次请求会重试（刚导入的 App 可能短暂返回 `APP_NOT_READY`，数据层先自动重试，仍失败时按 503 回答）。已有 ID 引用 `data.collection({ collectionId })` 跳过 ensure，可按原授权[读取回收集合历史](../../tier0-sdk-v2-uns/references/read.md#回收集合的历史读取)。
 
-运行中的进程在所用集合消失时会自愈（Preview 重置会删除集合，worker 或管理员可能归档集合）：UNS 以 `data.reason` 为 `COLLECTION_NOT_FOUND` 或 `COLLECTION_NOT_GRANTED` 拒绝调用时，数据层重新 ensure（重建并重新写入种子），并在集合 ID 确实变化时把该调用重试一次。每个 client 每 30 秒最多重建一次；`APP_GRANT_REVOKED`（管理员决定）从不重试。延续旧集合游标的分页、`updateMany` / `deleteMany` 的续写直接失败，不会重试。
+声明集合的调用被 `COLLECTION_NOT_FOUND` 或 `COLLECTION_NOT_GRANTED` 拒绝时，数据层重新 ensure（重建并重新写入种子），并在集合 ID 确实变化时把该调用重试一次。每个 client 每 30 秒最多重建一次；已有 ID 引用不触发重建。历史读取成功、`APP_GRANT_REVOKED` 或 `OWNER_APP_TRASHED` 均不触发自愈。延续旧集合游标的分页、`updateMany` / `deleteMany` 的续写直接失败，不会重试。
 
 Preview（`environment: 'preview'`，`NODE_ENV` 不是 production 时的默认值）下，Schema 冲突或 ensure 警告会让请求失败并带上详情；部署环境只记录日志、继续服务。`ignored` 提示从不让请求失败：存储比声明更宽的部分记为 info，`ANNOTATION_NOT_APPLIED`（ensure 不会改写的描述）记为指向 `schema:replace` 的 warning。

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/errors.md

@@ -38,10 +38,10 @@ export function toResponse(error: unknown): Response {
 
 | code | 含义 |
 | --- | --- |
-| `DATA_NOT_CONFIGURED` (503) | 缺少 TIER0_API_HOST / TIER0_API_KEY（或 apiHost / apiKey） |
+| `DATA_NOT_CONFIGURED` (503) | 缺少 TIER0_API_HOST（或 apiHost），或缺少 TIER0_API_KEY（或 apiKey）。平台里两者都由平台注入；没绑 App 的会话两者都没有 |
 | `DATA_TIMEOUT` (503) | UNS 未在超时内应答（每次调用从开始算共 25 秒，含排队与重试，`transportTimeoutMs` 可调）；写入时 `outcomeUnknown` 为 true、不重试 |
 | `DATA_OVERLOADED` (503) | 本进程 6 个请求名额一直占满，调用在超时前没排到，**没有发出**（`execution: 'notStarted'`，`retry.safe`）；减少并发或合并读取 |
-| `DATA_ABORTED` (499) | 业务请求已中止（`runWithRequestContext(request, …)` 的 `request.signal`）：排队中的调用不再发出（`notStarted`），已发出的写入 `outcomeUnknown` |
+| `DATA_ABORTED` (499) | 业务请求已中止（`runWithAbortSignal(request.signal, …)` 传入的信号）：排队中的调用不再发出（`notStarted`），已发出的写入 `outcomeUnknown` |
 | `DATA_UNREACHABLE` (503) | 连不上数据服务（读会自动重试）；网关地址只在原始错误里，不进 message |
 | `HTTP_502` / `HTTP_503` / `HTTP_504` (503) | 网关在滚动发布、Pod 重启时未经 UNS 直接返回；读会自动重试，写入时 `outcomeUnknown` 为 true、不重试 |
 | `DATA_BAD_RESPONSE` (502) | UNS 应答不符合契约 |
@@ -58,7 +58,7 @@ export function toResponse(error: unknown): Response {
 
 | code | 含义与处理 |
 | --- | --- |
-| `SCHEMA_CONFLICT` (409) | 声明无法与存储合并，没有任何改动。`data.conflicts` 列出 `{ alias, path, reason, current?, declared? }`：`TYPE_CONFLICT` → 换新字段名；`LIMIT_EXCEEDED` → 拆分结构；`JOIN_UNSUPPORTED` → 存储中有声明无法放宽的节点，用 `schema:replace` 修复；`DATA_RULE_FIELD` → 员工数据规则（owner/state 字段）在用该路径，保持必填且类型不变，或请管理员修改规则；`OPEN_OBJECT` → 用 `z.object`；`ALIAS_IN_USE` → 选择未占用的 alias；`NAME_IN_USE` → 选择同目录下不同且有业务含义的 name，保留 alias，不拼随机后缀；`INVALID_INDEX` → 修正索引 |
+| `SCHEMA_CONFLICT` (409) | 声明无法与存储合并，没有任何改动。`data.conflicts` 列出 `{ alias, path, reason, current?, declared? }`：`TYPE_CONFLICT` → 换新字段名；`LIMIT_EXCEEDED` → 拆分结构；`JOIN_UNSUPPORTED` → 存储中有声明无法放宽的节点，用 `schema:replace` 修复；`OPEN_OBJECT` → 用 `z.object`；`ALIAS_IN_USE` → 选择未占用的 alias；`NAME_IN_USE` → 选择同目录下不同且有业务含义的 name，保留 alias，不拼随机后缀；`INVALID_INDEX` → 修正索引 |
 | `INVALID_REQUEST` (400)，`path=collections/<i>/directoryPath` | 新建集合缺少目录或路径非法。声明实际业务路径后再调用；不回退到缺少业务范围的根级 App 目录，不添加虚构层级 |
 | `SCHEMA_CONFLICT`，`data.reason=DIRECTORY_PATH_CONFLICT` | 路径被已归档目录或同名非目录对象占用；核对真实目录，不能自动恢复、改名或扩大授权 |
 | `DIRECTORY_PATH_NOT_APPLIED`（`ignored` 提示） | 已有 alias 的目录与声明不同；保留当前位置继续服务。需要移动时走明确授权的元数据操作，ensure 不迁移 |
@@ -80,7 +80,26 @@ export function toResponse(error: unknown): Response {
 | `APP_GRANT_REVOKED` (403) | 管理员撤销了本 App 对集合的授权；ensure 不会自动恢复，请管理员处理 |
 | `APP_QUOTA_EXCEEDED` (409) | `data.resource` 指出触达的每 App 上限（64）：`collections` → 归档不用的集合；`indexes` → 从声明删索引并 `schema:replace`；`archivedCollections` → 恢复一个或请管理员清理 |
 | `INDEX_QUOTA_EXCEEDED` (409) | Workspace 实际存在的索引已达 200；删除不用的索引 |
-| `COLLECTION_TOO_LARGE` (409) | archive / restore 最多处理 2000 条记录（`data.maxRecords`）；不要归档大集合 |
+| `COLLECTION_TOO_LARGE` (409) | 仅旧 recordsArchivedAt 墓碑恢复有 2000 条上限（`data.maxRecords`）；当前 archive / restore 保留记录，不受该上限限制 |
+| `OWNER_APP_TRASHED`（`data.reason`） | 所属 App 在回收站；恢复 App 后再写入，不触发自动重建 |
+| `DIRECTORY_IN_TRASH`（`data.reason`） | 子项随目录回收，需恢复原目录；不逐个恢复子项 |
 | `FORBIDDEN` (403) | Key 不能做该操作（其他 App 或共享集合），或 Key 已吊销 |
 
-记录调用上的 `data.reason`：`COLLECTION_NOT_GRANTED`（403，授权不覆盖该集合或操作）与 `COLLECTION_NOT_FOUND`（403/404，已归档或删除）会触发数据层重新 ensure；`APP_PERMISSION_MISSING`（403，`data.missingPermission`）表示 Key 缺少权限，例如删除记录需要 `uns.delete`——业务记录通常以状态结束（`CANCELLED`、`ARCHIVED`）而不是删除。
+记录调用上的 `data.reason`：`COLLECTION_NOT_GRANTED`（403，授权不覆盖该集合或操作）与 `COLLECTION_NOT_FOUND`（403/404，集合不存在或写入目标已回收）仅对声明集合触发[自愈](consistency.md#首次访问与自愈)，已有 ID 引用直接报告错误；回收不使已有授权的历史读取失效。`APP_PERMISSION_MISSING`（403，`data.missingPermission`）表示 Key 缺少权限，例如删除记录需要 `uns.delete`——业务记录通常以状态结束（`CANCELLED`、`ARCHIVED`）而不是删除。
+
+## 平台代理模式的错误
+
+只在平台代理模式下出现：`TIER0_RUNTIME` 为 `deployed` / `preview` 而进程里没有 `TIER0_API_KEY`，SDK 不发凭据、请求经节点代理（`sbx-api-proxy`）由它附加 App 的 Key。当前平台给 App 注入 `TIER0_API_KEY`，不会进入这个模式。代理自己产生的错误带响应头 `X-Tier0-Proxy: not-forwarded`，响应体 `{code, message, retry_after_ms?}`，请求**没有到达平台**，所以 `execution` 是 `notStarted`，写入重发也安全。`DataError.code`、`UnsV2Error.code`、`ApiError.errorCode` 都是下表的 `code`。
+
+| code | 含义与处理 |
+| --- | --- |
+| `sbx_proxy_not_ready` (503) | 代理刚启动，还没拿到这台 VM 的绑定。SDK 已按 `retry_after_ms` 重试 3 次，仍失败就稍后再试 |
+| `sbx_proxy_limited` (429) | 超过这台 VM 的上限（64 个并发请求、50 rps、8 个 SSE、16 条 MQTT 等）。SDK 已重试 3 次；减少并发 |
+| `sbx_proxy_credential_pending` (503) | 绑定在，但 App 的 Key 还没送到代理。SDK 已按 `retry_after_ms` 重试 3 次，仍失败就稍后再试 |
+| `sbx_proxy_no_credential` (403) | 这台 VM 永远没有 Key：会话没有绑定 App，只能调 `/openapi/v2/info`。不重试 |
+| `sbx_proxy_unbound` (403) | 这台 VM 当前没有绑定：实例正在启动、停止或被替换，等平台恢复 |
+| `sbx_proxy_bad_request` (400) | 请求格式被拒：absolute-form、`CONNECT`、`Upgrade`、路径含 `.` / `..` / `//` / `%2f` / `%2e` / `%5c` / `;`、请求头超过 32 KiB 或 100 个 |
+| `sbx_proxy_forbidden` (403) | 缺 `X-Tier0-SDK: 1`，或带了 `Forwarded` / `X-Forwarded-*` / `X-Real-IP`。直接用 `fetch` / `curl` 时自己加 `X-Tier0-SDK: 1` |
+| `sbx_proxy_not_found` (404) | 路径不在代理白名单里：只转发 `/openapi/v2/uns/**`、`assets/**`、`notifications/send`、`notifications/get`、`platform/getMembers`、`apps/access-members/list`、`info`（白名单内但 App 的 Key 无权的接口，如 Source / Stream 管理、`assets/upload`，由 Backend 回 403；App 的 Key 在 `assets/` 下只能调 `assets/files/**`） |
+
+只有带 `X-Tier0-Proxy: not-forwarded` 的 `503` / `429` 会被 SDK 自动重试；平台返回的 5xx 不重试。

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/modeling.md

@@ -150,9 +150,11 @@ export const loginCodes = defineCollection({
 
 - 字段声明为 `z.number().int()`，存 Unix 毫秒（通常是 `Date.now()`）；记录在该时刻再过 `expireAfterSeconds`（60–31536000 秒）后被删除。删除有分钟级延迟，读取时仍要自己比较时间。
 - 每个集合最多 1 个 TTL 索引，只能是单个 `path`、不能 `unique`。缺这个字段的记录不会过期。
-- 过期删除是**物理删除**，不能 restore；软删除的记录同样按 TTL 清理。
+- 过期删除是**物理删除**，不能 restore；集合有效时，软删除的记录同样按 TTL 清理，集合回收后停止 TTL 清理。
 - ensure 只能新增 TTL 或把时间加长；缩短或去掉要通过 tier0 MCP 的 `schema:replace`。
 
+集合软删除和 App 回收保留查询索引，物理索引仍占配额；归档不释放索引空间，见[回收规则](../../tier0-sdk-v2-uns/references/delete.md#回收规则)。
+
 ## 种子数据
 
 种子是基线记录：固定 `_id`，各生命周期状态自洽，相互引用用这些 ID；每个集合最多 1000 条。只在 ensure 报告集合为 `created` 时写入一次（每 200 条一个原子分块，分块带固定幂等键，重试安全）；修改 `seed` 不会改动已存在的集合。不要在服务启动或列表为空时从代码插入基线数据。构建期可以对每条种子调用 `validateDocument(definition, document)` 校验。

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/read-write.md

@@ -91,7 +91,7 @@ export async function ordersScreen(page: number, selectedId: string) {
 | --- | --- |
 | `find(filter, { sort, limit, projection })` | 游标，每页最多 200 条；列表读取始终给 `limit` |
 | `findOne(filter)` | 无匹配返回 `null` |
-| `get(ids, { projection })` | 按 `_id` 读取，返回 `{ items, missing }`，`items` 按请求顺序（重复的 ID 只取第一次出现）；不存在、已删除或员工无权查看的 ID 一律进 `missing`。超过 100 个自动分批 |
+| `get(ids, { projection })` | 按 `_id` 读取，返回 `{ items, missing }`，`items` 按请求顺序（重复的 ID 只取第一次出现）；不存在或已删除的 ID 一律进 `missing`。超过 100 个自动分批 |
 | `findPage(filter, { sort, page, pageSize, maxCount })` | 页码分页，一次请求返回 `{ items, total: { count, capped }, page, pageSize }`；pageSize 最多 200，总数默认数到 10000（`maxCount` 最多 100000），超过时 `capped: true` |
 | `countDocuments(filter, { maxCount })` | 返回 `{ count, capped }`，默认数到 100000；只要阈值时给小的 `maxCount`（如角标 `99+`） |
 | `countBy(field, filter)` | 每个取值的数量 `[{ value, count }]`，从多到少；一次 `$group` |
@@ -161,26 +161,59 @@ export async function bumpAll(items: Collection<{ status: string; views: number
 
 ```ts
 import { z } from 'zod';
-import { createDataClient, defineCollection, runAsApp, type SubscriptionEvent } from '@tier0/sdk-v2/data';
+import { createDataClient, defineCollection, type SubscriptionEvent } from '@tier0/sdk-v2/data';
 
 const tickets = defineCollection({ alias: 'tickets', name: '问题工单', directoryPath: ['问题管理'], schema: z.object({ title: z.string(), status: z.enum(['OPEN', 'DONE']) }) });
 const data = createDataClient({ collections: [tickets] });
 
-/** 一个进程一条 App 级订阅，在进程内扇出给浏览器。 */
-export async function pumpChanges(send: (event: SubscriptionEvent) => void, signal: AbortSignal) {
-  await runAsApp(async () => {
-    for await (const event of data.subscribe({ collections: [tickets], signal })) {
-      // reset：续传位置失效或访问范围变化，浏览器应重新读取当前数据。
-      send(event);
-    }
-  });
+/** 服务端自己消费变更（例如刷新缓存）。 */
+export async function pumpChanges(handle: (event: SubscriptionEvent) => void, signal: AbortSignal) {
+  for await (const event of data.subscribe({ collections: [tickets], signal })) {
+    // reset：续传位置失效或访问范围变化，重新读取当前数据。
+    handle(event);
+  }
 }
 ```
 
-- 事件：`{ type: 'change', eventId, collection（alias）, collectionId, change: 'record' | 'delete', recordId, revision, occurredAt, restricted }`、集合级通知 `{ type: 'change', …, change: 'collection', restricted: true }`（没有 `recordId` / `revision`），或 `{ type: 'reset', reason, message? }`。心跳与重连在 SDK 内部处理；迭代抛出 `DataError` 表示不能再重试（如 403），正常结束只有 `signal` 中止或跳出循环。
+- 事件：`{ type: 'change', eventId, collection（alias）, collectionId, change: 'record' | 'delete', recordId, revision, occurredAt }` 或 `{ type: 'reset', reason, message? }`。心跳与重连在 SDK 内部处理；迭代抛出 `DataError` 表示不能再重试（如 403），正常结束只有 `signal` 中止或跳出循环。
 - 事件按写入事务的顺序到达，不是提交顺序，同一记录的 revision 可能乱序。SDK 已丢弃 revision 不大于该记录已投递 revision 的非 `delete` 变更；`delete` 一律投递（迟到的也投递），并清除该记录的 revision（同一 ID 再写入时可能从 1 开始）。收到事件后按 `recordId` 重新读取，不要用事件顺序推断记录的最终状态。
 - `reset`：`CURSOR_EXPIRED`（续传位置已被清理、游标无法解开或租户库已迁移）或 `SCOPE_CHANGED`（访问范围变化，例如集合不再可读）。重新读取当前数据；SDK 随后不带续传位置重新订阅。
-- `restricted: true`：该集合有员工数据规则。以 App 身份打开的订阅能看到所有记录的变更，所以默认把这类变更换成集合级通知，可以直接转发给任何员工的浏览器，浏览器再通过受规则约束的接口重新读取。只有不转发给浏览器的服务端逻辑才传 `restricted: 'record'` 拿完整事件（转发前仍须逐个经 `redactRestricted`）。
+- 订阅以 App 身份运行，看得到 App 被授权集合的全部变更，没有按当前用户的过滤。转发给浏览器时由 App 按访问者角色决定每个浏览器能知道哪些变更（见下一节）。
 - 默认订阅全部已声明的集合（最多 64 个）；`recordIds`（最多 100 个）只能配一个集合。
-- 订阅不占数据请求的并发名额，但每个租户的订阅数有上限（超出时 SDK 按 429 自动退避重连）：一个服务端进程只开一条订阅，在进程内扇出，不要每个浏览器连接开一条。App 刚导入还没就绪（`APP_NOT_READY`）时订阅会一直等待，不会结束。
+- 订阅不占数据请求的并发名额，但每个工作区的订阅数有上限（超出时 SDK 按 429 自动退避重连）：一个服务端进程只开一条订阅，在进程内扇出，不要每个浏览器连接开一条。App 刚导入还没就绪（`APP_NOT_READY`）时订阅会一直等待，不会结束。
 - 变更保留 24 小时；`lastEventId` 太旧时收到 `reset`。`lastEventId` 必须是收到过的事件 ID（可见 ASCII），否则调用时直接抛 `TypeError`。
+
+## 把变更推给浏览器
+
+浏览器不直连 UNS 或 MQTT。`createChangeRelay(data)` 在服务端进程里开一条 `data.subscribe`，转成可以挂在 App 路由上的 SSE 响应，`filter` 由 App 按访问者角色决定每个浏览器收到哪些变更：
+
+```ts
+import { z } from 'zod';
+import { createChangeRelay, createDataClient, defineCollection, type RecordChange } from '@tier0/sdk-v2/data';
+import { parseVisitorHeader, VISITOR_HEADER, type Visitor } from '@tier0/sdk-v2/server';
+
+const tickets = defineCollection({ alias: 'tickets', name: '问题工单', directoryPath: ['问题管理'], schema: z.object({ title: z.string() }) });
+const data = createDataClient({ collections: [tickets] });
+const relay = createChangeRelay(data); // 每进程一个
+
+/** App 自己的规则：哪些角色能看哪个集合。 */
+function canSee(visitor: Visitor, change: RecordChange): boolean {
+  return change.collection !== 'tickets' || visitor.appRoles.includes('support');
+}
+
+/** GET /api/changes */
+export function changes(request: Request): Response {
+  const visitor = parseVisitorHeader(request.headers.get(VISITOR_HEADER));
+  return relay.stream({
+    filter: (change) => canSee(visitor, change),
+    lastEventId: request.headers.get('Last-Event-ID'),
+    signal: request.signal,
+  });
+}
+```
+
+- 帧：`event: change`（`{ eventId, collection, change, recordId, revision, occurredAt }`，不带记录数据）、`event: reset`（`{ reason }`）、`event: unavailable`（`{ reason }`，上游连不上、仍在重试），每 15 秒一个只带 `id` 的帧推进位置（还没有位置时是注释）。浏览器用 `@tier0/sdk-v2/event-stream` 的 `openEventStream` 读（页面隐藏时断开、可见时带 `Last-Event-ID` 续传，转发器补发或回 `reset`），收到 `change` 后经 App 自己的接口重新读取（那里同样按角色过滤），收到 `reset` 重新加载整个视图。转发器不发 `retry:`，重连节奏由 `openEventStream` 决定。
+- `id` 是转发器自己的位置（`<epoch>.<seq>`），不是 UNS 游标，浏览器拿不到上游位置；只在上游能送达其后所有变更时才给。冷启动时上游第一次连上之前不给位置，连上后先给 `reset`（`upstream-started`）再给位置。上游失败或空闲关闭（最后一个浏览器离开 30 秒）后从最后的 UNS 位置重开，epoch 不变，不漏、不 reset；只有 UNS 回 `reset` 才换 epoch，上游重新连上后给浏览器发 `reset`。重连带 `Last-Event-ID`：在当前 epoch 最近 1000 条里找得到就补发之后的（同样经过 `filter`），找不到就只给这个浏览器一个 `reset`。
+- 上游连不上（超过订阅上限的 429、`APP_NOT_READY` 等）时 `relay.status` 是 `unavailable`，`onStatus(status, error)` 回调，`logger.warn` 记一次，浏览器收到 `event: unavailable`；上游恢复后状态回到 `ready`。
+- `filter` 同步调用，对实时和补发的变更都生效；抛错的变更不发。事件只有标识，但 `recordId` 本身也可能透露信息：规则按记录的，过滤时就把这个浏览器无权知道的记录去掉。
+- 每个浏览器连接 10 分钟（±10%）后结束，浏览器重连时路由重新认证。选项：`collections`、`bufferSize`、`idleCloseMs`、`restartIntervalMs`、`maxRestartIntervalMs`、`heartbeatMs`、`maxStreamMs`、`onStatus`、`logger`。

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/schema-evolution.md

@@ -38,4 +38,6 @@ export function replaceBody(expectedRevision: number) {
 
 Schema 中 `ignored`、`warnings`、`conflicts`、`violations` 的路径用 `.` 连接属性，用 `[]` 表示数组元素（`lines.[].qty`）。
 
+集合 archive 的数据与授权变化见[回收规则](../../tier0-sdk-v2-uns/references/delete.md#回收规则)，restore 的范围与授权区别见[恢复](../../tier0-sdk-v2-uns/references/restore.md)。
+
 新声明的 number/integer 默认带 double/int32 格式；ensure 不改写已有字段注解，原无格式字段仍保持 legacy 显示。已有字段格式迁移需读取并保留完整 Schema，先通过 schema:replace dryRun 检查，再按明确迁移授权执行。