@tier0/sdk-v2 0.6.3 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.6.3",
+  "version": "0.7.2",
   "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
   "license": "MIT",
   "type": "module",
@@ -155,7 +155,7 @@
   "scripts": {
     "sync:contracts": "node scripts/sync-contracts.mjs",
     "generate": "node scripts/generate-openapi.mjs && node scripts/generate-uns-v2.mjs",
-    "check:contracts": "node scripts/check-contracts.mjs && node --test scripts/retired-stream-probe.test.mjs scripts/retired-http-push.test.mjs scripts/sync-contracts.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",
+    "check:contracts": "node scripts/check-contracts.mjs && 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/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",
     "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",
@@ -199,7 +199,9 @@
     "vitest": "^4.1.7",
     "esbuild": "^0.25.0",
     "yaml": "^2.8.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
   },
   "agents": {
     "skills": [
@@ -239,10 +241,6 @@
         "name": "tier0-sdk-v2-system",
         "path": "./skills/tier0-sdk-v2/tier0-sdk-v2-system"
       },
-      {
-        "name": "tier0-sdk-v2-controls",
-        "path": "./skills/tier0-sdk-v2/tier0-sdk-v2-controls"
-      },
       {
         "name": "tier0-sdk-v2-agent",
         "path": "./skills/tier0-sdk-v2/tier0-sdk-v2-agent"

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

@@ -1,6 +1,6 @@
 ---
 name: tier0-sdk-v2
-description: 使用 @tier0/sdk-v2 开发 Tier0 云端 TypeScript/JavaScript 应用：Source 数据源、Stream 处理程序、UNS 集合与记录、App 自有数据（@tier0/sdk-v2/data）、通知、文件存储、MQTT、成员、系统身份与能力、Controls 和 Agent，按任务进入对应子 Skill，并处理配置、身份和框架集成。
+description: 使用 @tier0/sdk-v2 开发或迁移 Tier0 云端 TypeScript/JavaScript 应用：Source 数据源、Stream 处理程序、UNS 集合与记录、App 自有数据（@tier0/sdk-v2/data）、通知、文件存储、MQTT、成员、系统身份与能力和 Agent，按任务进入对应子 Skill，并处理配置、身份和框架集成。
 ---
 
 # Tier0 SDK v2 应用集成
@@ -20,7 +20,6 @@ description: 使用 @tier0/sdk-v2 开发 Tier0 云端 TypeScript/JavaScript 应
 | 附件、头像、导入导出、生成报告 | `client.files` | [文件](tier0-sdk-v2-files/SKILL.md) |
 | 实时主题订阅/发布 | `@tier0/sdk-v2/mq`、`client.mqttAuth` | [MQTT](tier0-sdk-v2-mq/SKILL.md) |
 | Workspace 收件人/成员检索、App 可用成员 | `client.members` | [成员](tier0-sdk-v2-members/SKILL.md) |
-| 调用已发布的 Control | `client.controls` | [Controls](tier0-sdk-v2-controls/SKILL.md) |
 | Agent 作业、运行、分析结果和卡片 | `client.agent` | [Agent](tier0-sdk-v2-agent/SKILL.md) |
 
 每个领域 Skill 可单独使用，无需先加载本文件。Source → Stream → UNS 是接入、处理与数据存储三个领域；不是要求每个数据读取场景都创建一套流水线。通知和系统能力独立于这条链路。
@@ -48,12 +47,23 @@ export async function inspectConnection() {
 | Source、Stream、UNS | 完整 `{ code, msg, requestId, data }` | `UnsV2Error` / `UnsV2OutcomeUnknownError` |
 | 平台 v2，如 system、members、agent、mqttAuth | 解包后的 `data` | `ApiError` / `TransportError` |
 | notifications | 直接对象，如 `messageId`、`status` | `ApiError` |
-| controls、capabilities | 专属响应对象 | `ControlError` / `CapabilityError` |
+| capabilities | 专属响应对象 | `CapabilityError` |
 
 方法存在不等于目标环境已部署或当前 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，不代表它们仍属于数据入口。
 
+## 从首版入口迁移
+
+- `client.uns.sourceList(body)` → `client.source.documents.list(body)`。
+- `client.uns.sourceDocumentGet(body)` → `client.source.documents.get(body)`。
+- `client.uns.streamProgramDeploy(body)` → `client.stream.programs.deploy(body)`。
+- `client.uns.streamDocumentValidate(body)` → `client.stream.documents.validate(body)`。
+- `client.uns.recordFind(body)` 保持不变。
+- 低层 `createUnsV2Client` 保留完整生成契约，供契约工具使用；业务主入口不再把 Source/Stream 管理混入 `client.uns`。
+
 React/Vue 示例与验签见 [集成参考](references/integration.md)。完成接入时验证目标入口、真实身份、响应解包和错误分支；SDK 本地测试通过不代表环境联调完成。
 
-公开 HTTP 入口统一为 `/openapi/v2`。Source 配置用 documents.*，Stream 草稿用 documents.*、发布用 programs.deploy；App 数据层提供 insertMany/findOneAnd*/distinct 等便捷方法。业务代码优先使用领域入口，底层 createUnsV2Client 供契约工具使用。
+Stream 请求与消息交互由独立包 `@tier0/sdk` 的 `client.streams.requests` / `client.streams.messages` 提供；本包负责数据访问和 Source/Stream 管理，不重复实现交互 API。Scaffold 分别接入这两个包，不能将本包的 `client.stream` 管理接口当作运行时请求入口。
+
+本包公开 HTTP 入口统一为 `/openapi/v2`。旧的重复操作已退役，不生成兼容调用或回退。Source 配置用 documents.*，Stream 草稿用 documents.*、发布用 programs.deploy；App 数据层仍提供 insertMany/findOneAnd*/distinct 等便捷方法。历史旧写结果未知时先核对业务状态，不能转换路由后盲目重放。

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

@@ -69,7 +69,7 @@ export async function publishMeasurement(mq: Tier0MQClient, topic: string, value
 }
 ```
 
-publish 目前在建立连接并调用 MQTT 库发布后返回，不等待业务执行确认，也不保证已收到 broker PUBACK。需要闭环时使用业务 ACK 主题/关联 ID 或 Control 契约，不能把 Promise resolve 当成设备执行完成。
+publish 目前在建立连接并调用 MQTT 库发布后返回，不等待业务执行确认，也不保证已收到 broker PUBACK。需要闭环时使用业务 ACK 主题/关联 ID 或独立交互 SDK 的 Stream 请求合同，不能把 Promise resolve 当成设备执行完成。
 
 订阅内部 QoS 为 1；发布默认 QoS 0、retain=false。业务消费者需考虑重复消息。对象 payload 经 JSON.stringify，不能直接包含 bigint；按协议约定编码精确值，不假设 MQTT 自动使用 UNS 的无损 codec。
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-mq/references/quickstart.md

@@ -58,7 +58,7 @@ export async function publishEvent(mq: Tier0MQClient, topic: string, eventId: st
 }
 ```
 
-payload 必须符合实际主题契约；对象用 JSON.stringify，不可包含 bigint。publish resolve 不证明已收 PUBACK，更不证明设备执行；业务闭环用关联 ID/ACK 或 Control。订阅 QoS 1，发布默认 QoS 0/retain=false，消费端考虑重复消息。
+payload 必须符合实际主题契约；对象用 JSON.stringify，不可包含 bigint。publish resolve 不证明已收 PUBACK，更不证明设备执行；业务闭环用关联 ID/ACK 或独立交互 SDK 的 Stream 请求。订阅 QoS 1，发布默认 QoS 0/retain=false，消费端考虑重复消息。
 
 ## 事件、背压和鉴权
 

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

@@ -26,13 +26,13 @@ Source 维护连接配置、认证引用与源状态。脚本处理用 [Stream](
 1. Source 配置统一使用 documents.*，原生文档为 `{name,protocol,config}`，HTTP API 显式指定 `config.role`。HTTP 统一为 `protocol: http-api` + `config.role: client/server`；Client 主动请求，Server 接收入站请求，不能互换。HTTPServer 统一接收入站请求，固定前缀后的路由和响应时机属于 Stream。
 2. 已有 ID 和 revision 时优先用 documents.update 的 patch，避免额外 get；完整替换 document 前读取完整文档，安全列表摘要不能无损回写。原生 ID 是十进制字符串，revision 原样传递，不转 Number。
 3. 现有 Source 修改、启停、删除都要 expectedRevision。没有任何 Stream 引用时可直接提交；有草稿、活动、历史或不可见引用时仍需 confirmedImpactRevision。先形成精确意图，再读取全部影响分页；回执不可合成、跨意图复用或静默刷新。提供的回执始终严格校验，不自动获取并同意影响。
-4. 配置中保留认证/TLS 引用，不写明文秘密；HTTP Client 新凭据走创建专用 credentials；Server 不携带 Client auth/TLS 配置。
+4. 配置中保留认证/TLS 引用，不写明文秘密；HTTP Client 新凭据走创建专用 credentials，普通创建省略 credentials.method（服务端默认 REQUEST 基址绑定），真实 method/path/query 由 Stream 定义。Basic/Bearer 显式凭据方法限制精确 URL 和方法，OAuth 旧 GET 保留既有兼容语义，不自动扩大旧授权；Server 不携带 Client auth/TLS 配置。
 5. desiredState 不代表实际健康，保存配置不代表 Stream 已切换至新 configRevision。运行状态另行读取。
 
 ## 返回值与异常
 
 所有调用返回完整 code/msg/requestId/data。documents.create/update 的预检返回 validated/sideEffects，提交返回完整 Source view，可直接使用其中的文档和 revision，无需额外 get；批量状态/删除返回 Outcome。只有 committed 且无项错误才可报告提交成功；accepted/jobId 继续查询作业。预检按需使用，不是每次提交的必经步骤。
 
-需要查看历史用 source.history({id,beforeRevision,size})，按 nextBeforeRevision 继续；探测用 source.probe，其外部系统访问应属于当前任务。连接配置修改使用 documents.update，遵守同一影响确认契约。
+需要查看历史用 source.history({id,beforeRevision,size})，按 nextBeforeRevision 继续；探测用 source.probe，其外部系统访问应属于当前任务。配置校验或连接探测成功不证明某个 Stream 请求已获授权或采集成功，实际结果看对应发布的 runs。连接配置修改使用 documents.update，遵守同一影响确认契约。
 
 UnsV2Error 表示已知拒绝；UnsV2OutcomeUnknownError 表示可能已写入。保存 requestId、原请求和意图键，先查详情/历史/作业对账。取消等待不撤销服务端操作；SDK 不自动重试。权限不足不能解释为资源不存在。

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

@@ -41,7 +41,9 @@ HTTP Server 同样使用 `protocol: http-api`，角色为 `config.role: server`
 
 ## HTTP Client Bearer 凭据
 
-token 从服务端密钥提供者取得，不写入脚本、文档、日志或仓库。
+Source 保存 API 基址和认证；实际请求的 method/path/query 由 Stream 设置。例如 endpoint 使用 `https://inventory.example.com/api/v1`，再由 [Stream 示例](../../tier0-sdk-v2-stream/references/create.md)请求 `GET inventory`。token 从服务端密钥提供者取得，不写入脚本、文档、日志或仓库。
+
+普通创建省略 `credentials.method`，服务端按 `REQUEST` 绑定 Source 基址。REQUEST 是凭据适用范围标记，不是发送给上游的 HTTP 方法；实际 GET 请求仍由执行宿主逐次授权。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
@@ -53,7 +55,7 @@ export async function createAuthenticatedHttpSource(
   const saved = await client.source.documents.create({
     dryRun: false, idempotencyKey: intentKey,
     document: { name, protocol: 'http-api', config: { role: 'client', endpoint, options: {} } },
-    credentials: { method: 'GET', kind: 'bearer', material: { token } },
+    credentials: { kind: 'bearer', material: { token } },
   });
   if (!('id' in saved.data)) throw new Error('未返回 Source ID');
   return { receipt: saved, current: saved.data };
@@ -92,12 +94,14 @@ Server 的固定前缀 `/ingest/v1/{workspaceId}/{sourceId}` 和 Bearer 要求
 
 | kind | material | method |
 | --- | --- | --- |
-| basic | username、password | 省略时 REQUEST；可显式绑定受限 HTTP 方法 |
-| bearer | token | 省略时 REQUEST；上方 GET 示例保持明确的方法限制 |
+| basic | username、password | 省略时 REQUEST；显式方法绑定精确 URL 和该方法 |
+| bearer | token | 省略时 REQUEST；显式方法绑定精确 URL 和该方法 |
 | apiKey | headerName、value | 省略或 REQUEST |
-| oauth2ClientCredentials | tokenUrl、clientId、clientSecret；可选 scope、clientAuthentication | 省略、REQUEST 或 GET |
+| oauth2ClientCredentials | tokenUrl、clientId、clientSecret；可选 scope、clientAuthentication | 普通创建省略；旧 GET 保留既有兼容语义 |
+
+Basic/Bearer 显式 `credentials.method: 'GET'` 表示凭据只用于所绑定精确 URL 的 GET，不表示该基址下所有 GET 都可使用：绑定 `/api/v1` 不授权 `/api/v1/inventory?limit=5000`。仅在任务明确需要该限制时传入；已有绑定保持原限制，不自动迁移或在拒绝后回退 REQUEST。
 
-OAuth 的 `clientAuthentication` 支持 `client_secret_post`（默认）和 `client_secret_basic`。REQUEST 表示绑定 Source 基址，实际路径和方法仍由执行宿主逐次授权；显式方法的已有绑定不能解释成 REQUEST 的基址范围。vendor SESSION 合同独立保留，不是此 inline 创建的 method，也不新增独立公开凭据 API。
+OAuth 的 `clientAuthentication` 支持 `client_secret_post`（默认）和 `client_secret_basic`；method 接受省略、REQUEST 或旧 GET，旧 GET 保留现有兼容语义，不能把 Basic/Bearer 的精确 URL 规则跨认证类型套用。普通创建仍省略 method。vendor SESSION 合同独立保留，不是此 inline 创建的 method，也不新增独立公开凭据 API。
 
 ```ts
 import { createClient, type Tier0Client, type CloudSourceCreateCredentials } from '@tier0/sdk-v2';

package/skills/tier0-sdk-v2/tier0-sdk-v2-source/references/protocols.md

@@ -39,4 +39,4 @@ HTTP Client 示例不能用于 Server。HTTPServer 通过 `source.documents.*`
 
 Cloud 的角色位于 `config.role`；Enterprise 投影的顶层 `role` 不能直接抄入 Cloud 管理文档。Server 配置见[创建](create.md)，以 `http://managed` 和空 options 保存，不从 Client 模板推导。
 
-HTTP Client 的单条 inline 认证支持 basic / bearer / apiKey / oauth2ClientCredentials，method 省略时由服务端按 REQUEST 绑定 Source 基址；显式方法限制保持不变。APIKey 材料为 headerName/value，OAuth 可提供 clientAuthentication。见[创建](create.md)。
+HTTP Client 的单条 inline 认证支持 basic / bearer / apiKey / oauth2ClientCredentials。普通创建省略 credentials.method，由服务端按 REQUEST 绑定 Source 基址；实际 method/path/query 在 Stream 设置。Basic/Bearer 显式凭据方法同时限制精确 URL，不覆盖基址下的子路径；存量绑定保持限制，不自动扩大权限。APIKey 材料为 headerName/value，OAuth 可提供 clientAuthentication，旧 OAuth GET 保留既有兼容语义。见[创建](create.md)。

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

@@ -26,7 +26,7 @@ description: 使用 @tier0/sdk-v2 的 client.stream 创建、查询、修改和
 | Runtime program | name、script 字符串、sourceBindings、timeoutMs | documents.create/update/validate({program}) |
 | 云端原生文档 | name、model、script 对象、sources、entries | documents.create/get/update/validate |
 
-程序必须是完整 `module.exports = api => { ... }`，执行器 API 是 api.sources/api.uns/api.stream，与 npm 包的 client.source 不同。Runtime sourceBindings 为 sourceId/configRevision/acquisition；原生 sources 还使用 alias/resources。连接凭据不进脚本或 acquisition，秘密材料由 Source 执行宿主管理，不通过脚本读取、记录或返回。定时入口使用 api.stream.every；npm 的 client.controls 管理入口不作为 Goja 的 Stream 注册参数。
+程序必须是完整 `module.exports = api => { ... }`，执行器 API 是 api.sources/api.uns/api.stream，与 npm 包的 client.source 不同。Runtime sourceBindings 为 sourceId/configRevision/acquisition；原生 sources 还使用 alias/resources。连接凭据不进脚本或 acquisition，秘密材料由 Source 执行宿主管理，不通过脚本读取、记录或返回。定时入口使用 api.stream.every，不传播旧注册别名；App 请求与消息交互由独立 @tier0/sdk 的 client.streams.requests/messages 提供，不作为 Goja 注册参数。
 
 ## 核心约束
 

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

@@ -15,6 +15,8 @@
 
 先按[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 负责基址和认证，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 或自动扩大凭据授权来绕过拒绝。
+
 ```ts
 import { createClient, type Tier0Client, type RuntimeStreamDefinition, type CloudSourceDocumentView } from '@tier0/sdk-v2';
 
@@ -34,7 +36,7 @@ export async function createHttpStream(
       'module.exports = api => {',
       '  const upstream = api.sources.use({ id: ' + JSON.stringify(sourceId) + ', resources: [] });',
       '  api.stream.every({ id: "tick", intervalMs: 60000 }, async () => {',
-      '    const response = await upstream.request({ method: "GET", path: "orders" });',
+      '    const response = await upstream.request({ method: "GET", path: "inventory", query: { limit: "5000" } });',
       '    return response.data;',
       '  });',
       '};',
@@ -48,10 +50,12 @@ export async function createHttpStream(
 }
 ```
 
-将 path="orders"、60 秒周期改为业务实际值。示例保存草稿，不部署，也不将返回值自动写入 UNS；需要写入集合时按执行器能力定义 api.uns 操作。resources=[] 是空冻结资源集，不是通配授权。源地址和凭据留在 Source，不能拷进 acquisition 或脚本。
+将 path="inventory"、query 和 60 秒周期改为业务实际值。示例保存草稿，不部署，也不将返回值自动写入 UNS；需要写入集合时按执行器能力定义 api.uns 操作。resources=[] 是空冻结资源集，不是通配授权。源地址和凭据留在 Source，不能拷进 acquisition 或脚本。
 
 创建 data 为 CloudStreamDocumentView 或预检结果，实际保存返回 id、revision 和完整 document；预检不生成 ID。需要展示预检时单独调用 documents.validate({program})；普通保存无需先校验再保存。当前后端创建/校验需要注册 Worker 可用。TEMPORARILY_UNAVAILABLE 不代表脚本一定错误。
 
+validate 检查配置、程序和可确定的绑定问题，不执行任意业务分支，也不证明上游可达。尤其是运行时拼接的 path/query，仍需在授权范围内执行代表性采集，并检查本次发布的 runs 与业务结果；一次成功也只覆盖实际执行的请求。Source 连接探测和 isolated-sample 都不能替代真实采集验证。
+
 创建结局未知时先按已知 ID 或业务标识核对状态；允许重试时保留原请求与幂等键。
 
 原生编辑器形态 `documents.create({dryRun, document})` 的 document 为 name/model/script对象/sources/entries，script 为 `{code,timeoutMs}`，sources 用 alias/sourceId/configRevision/resources/acquisition。不要把上面的 script 字符串直接塞入原生文档。

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

@@ -84,6 +84,6 @@ export async function createHttpServerEarlyReplyStream(
 }
 ```
 
-`ctx.reply` 只用于 HTTP `api.stream.onRequest`，一次执行只回复一次；不要在 `every`、Control 或普通事件 handler 中调用，也不增加 npm App API 或公开 HTTP endpoint。示例先发 202 再写 Record，202 表示已回复接受，不能报告写入或提交成功；失败通过 Stream 运行记录检查，不能再发送第二份响应。
+`ctx.reply` 只用于 HTTP `api.stream.onRequest`，一次执行只回复一次；不要在 `every`或普通事件 handler 中调用，也不增加 npm App API 或公开 HTTP endpoint。示例先发 202 再写 Record，202 表示已回复接受，不能报告写入或提交成功；失败通过 Stream 运行记录检查，不能再发送第二份响应。
 
 回复后的处理仍受 Stream timeout（本例 5000 ms）、并发上限和实时权限约束。客户端断线不会取消已回复后的执行，服务 shutdown 仍可取消。进程崩溃不保证重放；业务若需持久投递、去重或恢复，必须另行设计，不能把 `ctx.reply` 当作持久队列。凭据和权限均沿用现有 Source/Stream 合同。

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

@@ -2,6 +2,8 @@
 
 创建并发布时，将 [创建](create.md) 或 [修改](update.md) 回执中的草稿直接交给 [发布](deploy.md)，再用发布回执的 activeRelease [观察运行](read.md#观察本次发布)，无需在发布前后各 get 一次。只有缺少当前草稿、处理版本冲突或需要最新状态时才 [查询](read.md)。停用、回滚和 [删除](delete.md) 按任务选择，不自动执行整套生命周期。
 
+HTTP 采集的常规顺序是选定或创建 Source → 用 Source 回执绑定并保存 Stream → 发布 → 观察该发布的真实采集。Source 保存基址和认证，Stream 指定 method/path/query。预检按需使用；静态校验只能发现可确定的问题，脚本动态请求仍需通过代表性实际运行验证，不能把配置通过、网络可达或样例通过等同于采集成功。
+
 ## 原生文档样例测试
 
 方法：stream.sampleTest；输入 document、entryId、input。document 来自 documents.get 的完整草稿，entryId 必须在该文档注册的 entries 内。

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

@@ -53,3 +53,7 @@ export async function readPublishedRuns(
 ```
 
 此函数只读一页。items 为空但 nextCursor 非空时，下一页仍可能有匹配记录；达到调用方的观察时限就报告“尚未观察到”。匹配记录也要检查 status、entryId 和时间，不能把存在记录当成执行成功。历史幂等回执若缺少 activeRelease，应保留为未确认，不能用当前 head 的发布号代替。
+
+失败或结果未知的运行可带 `error:{code,stage,message,repair,sourceRequest?}` 安全诊断。`SOURCE_TARGET_SCOPE_MISMATCH`、`stage:validate_binding` 表示请求超出 Source 凭据范围，应检查绑定基址与实际 method/path/query，保留原授权限制。`sourceRequest:notDispatched` 只证明失败的这一次 Source 请求未发送，不能推断整个 Stream 未开始或此前没有写入。
+
+`EXECUTION_FAILED` 和 `RESULT_UNKNOWN` 是安全通用诊断，分别保留失败和结果未知的区别。按 code/stage 判断，展示服务端 message/repair；没有 error 的旧记录仍按 status 解释，不补造原因，也不因可重试猜测而自动重新执行。运行诊断不包含 token、凭据引用或完整请求 URL。

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

@@ -43,13 +43,18 @@ info 返回 name/version/mqttBroker/capabilities，字段可能省略。MQTT bro
 | 字段/状态 | 判断 |
 | --- | --- |
 | releaseEnabled | 平台/Workspace 发布开关，不代表运行时已准备好 |
-| allowed | 当前身份的授权摘要，不是所有具体 Control 的执行许可 |
+| allowed | 当前身份的授权摘要，不是某个具体操作的执行许可 |
 | enabled、state=ready | 服务端评估就绪 |
 | availability=available | 能力可用性，不是设备在线、业务执行或 ACK |
 | disabled / not_supported / unavailable | 展示具体不可用原因，不强制调用 |
 | readiness_unknown | 保留未知状态，不能按成功处理 |
+| operations | Source / Stream 各操作独立判断；整体不可用不等于读取或安全停用不可用 |
+| reasonCode / checkedAt / validUntil | 保留服务端原因及证明时间，过期后重新发现，不把旧证明当成持续就绪 |
+| requiresResourceCheck | 实际调用仍要检查具体资源的权限、配置和依赖 |
 
-能力目录当前识别 namespace.v2、source、stream、control.v1、control.invoke.v1。Source/Stream 的 contractVersions 使用 openapi/v2，不要求或返回解释器版本。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。
+本数据 SDK 的能力目录识别 namespace.v2、source、stream；其他 SDK 的可选交互能力按各自合同处理，不阻断 Namespace 发现。Source/Stream 的 contractVersions 使用 openapi/v2，不要求或返回解释器版本。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。顶层要求受支持的核心 OpenAPI v2 合同，已识别能力也必须满足其合同；不要求全局交互 SDK 标签，不把未知能力投影为已支持。
+
+发现统一使用 `POST /openapi/v2/capabilities/discover`，请求为 `{}`，不接受 Workspace 参数。Cloud / Enterprise 返回同一合同；此 SDK 只消费 Namespace、Source、Stream 管理能力；App 交互域由 App SDK 提供，其版本不作为管理接口的前置条件。SDK 只投影已知操作与公开诊断字段；未知扩展不被解释为就绪，不自动重试。
 
 ## 定位问题
 

package/dist/cjs/controls.d.ts

@@ -1,105 +0,0 @@
-import { type HttpClient, type ClientConfig } from './openapi/client.js';
-import { type CloudTransportConfig } from './cloud-transport.js';
-import { type UnsV2Execution, type UnsV2Retry } from './uns-v2/client.js';
-import type { UnsV2JSONValue } from './uns-v2/generated.js';
-/** Control convenience API over the canonical UNS v2 routes. Exact numbers are preserved. */
-export type ControlJSON = UnsV2JSONValue;
-export interface PublicControl {
-    code: string;
-    name: string;
-    description: string;
-    contractVersion: string;
-    inputSchema: Record<string, ControlJSON>;
-    outputSchema: Record<string, ControlJSON>;
-    sideEffect: 'read' | 'write';
-    idempotency: 'none' | 'optional' | 'required';
-    timeoutMs: number;
-    status: string;
-}
-export interface ControlDiscoverOptions {
-    page?: number;
-    size?: number;
-    search?: string;
-}
-export interface ControlDiscoverResponse {
-    total: number;
-    list: PublicControl[];
-}
-/** Shared HTTP settings. The server still resolves the Control binding and authorization. */
-export interface ControlTransportConfig extends CloudTransportConfig {
-}
-export interface CloudClientConfig extends ClientConfig, ControlTransportConfig {
-}
-export declare const DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = 60000;
-export interface ControlInvokeOptions {
-    /** Stable caller-owned key for one business intent, at most 128 UTF-8 bytes. Never generated or retried by the SDK. */
-    idempotencyKey?: string;
-}
-export interface ControlInvokeResponse<Result = ControlJSON> {
-    code: string;
-    contractVersion: string;
-    result: Result;
-    runID: string;
-    status: string;
-    /** True only when the server explicitly reports an idempotent replay. */
-    replayed: boolean;
-}
-export interface ControlErrorInfo {
-    /** HTTP status, absent when no HTTP response was received. */
-    status?: number;
-    /** Canonical UNS error.code, or an SDK-local CONTROL_* transport/protocol code. */
-    errorCode: string;
-    runID?: string;
-    contractVersion?: string;
-    runStatus?: string;
-    replayed?: boolean;
-    requestId?: string;
-    execution?: UnsV2Execution;
-    retry?: UnsV2Retry;
-    reason?: string;
-    details?: Record<string, unknown>[];
-    data?: unknown;
-}
-/** No Control error is automatically retried, including authentication failures. */
-export declare class ControlError extends Error {
-    readonly status?: number;
-    readonly errorCode: string;
-    readonly runID?: string;
-    readonly contractVersion?: string;
-    readonly runStatus?: string;
-    readonly replayed?: boolean;
-    readonly requestId?: string;
-    readonly execution?: UnsV2Execution;
-    readonly retry?: UnsV2Retry;
-    readonly reason?: string;
-    readonly details?: Record<string, unknown>[];
-    readonly data?: unknown;
-    readonly retryable = false;
-    constructor(message: string, info: ControlErrorInfo);
-}
-/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */
-export declare class ControlResultUnknownError extends ControlError {
-    readonly outcomeUnknown = true;
-    constructor(info: ControlErrorInfo);
-}
-export interface ControlHandle<Input = ControlJSON, Result = ControlJSON> {
-    describe(): Promise<PublicControl>;
-    /**
-     * One POST only. Input is opaque business JSON, including fields named streamId,
-     * entryId, deploymentVersion or timeoutMs. Only the server chooses binding/version/timeout.
-     * Generic types are caller assertions; the server validates the contract schemas.
-     */
-    invoke(input: Input, options?: ControlInvokeOptions): Promise<ControlInvokeResponse<Result>>;
-}
-export declare class ControlsClient {
-    private readonly uns;
-    constructor(resolveClient?: () => HttpClient, config?: ControlTransportConfig);
-    private post;
-    /** Discover visible contracts; defaults and authorization are resolved by the server. */
-    discover(options?: ControlDiscoverOptions): Promise<ControlDiscoverResponse>;
-    use<Input = ControlJSON, Result = ControlJSON>(selector: {
-        code: string;
-    }): ControlHandle<Input, Result>;
-}
-/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */
-export declare const controls: ControlsClient;

package/dist/cjs/controls.js

@@ -1,172 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.controls = exports.ControlsClient = exports.ControlResultUnknownError = exports.ControlError = exports.DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = void 0;
-const client_js_1 = require("./openapi/client.js");
-const cloud_transport_js_1 = require("./cloud-transport.js");
-const client_js_2 = require("./uns-v2/client.js");
-const codec_js_1 = require("./uns-v2/codec.js");
-exports.DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = cloud_transport_js_1.DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS;
-/** No Control error is automatically retried, including authentication failures. */
-class ControlError extends Error {
-    status;
-    errorCode;
-    runID;
-    contractVersion;
-    runStatus;
-    replayed;
-    requestId;
-    execution;
-    retry;
-    reason;
-    details;
-    data;
-    retryable = false;
-    constructor(message, info) {
-        super(message);
-        this.name = 'ControlError';
-        this.status = info.status;
-        this.errorCode = info.errorCode;
-        this.runID = info.runID;
-        this.contractVersion = info.contractVersion;
-        this.runStatus = info.runStatus;
-        this.replayed = info.replayed;
-        this.requestId = info.requestId;
-        this.execution = info.execution;
-        this.retry = info.retry;
-        this.reason = info.reason;
-        this.details = info.details;
-        this.data = info.data;
-    }
-}
-exports.ControlError = ControlError;
-/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */
-class ControlResultUnknownError extends ControlError {
-    outcomeUnknown = true;
-    constructor(info) {
-        super('Control result is unknown; execution may have occurred. Do not automatically retry.', info);
-        this.name = 'ControlResultUnknownError';
-    }
-}
-exports.ControlResultUnknownError = ControlResultUnknownError;
-function record(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function keys(value, allowed) {
-    if (!record(value) || Reflect.ownKeys(value).some(key => typeof key !== 'string' || !allowed.includes(key))) {
-        throw new TypeError('Tier0 SDK: unsupported Control option.');
-    }
-}
-function json(value, seen = new Set()) {
-    if (value === null || typeof value === 'string' || typeof value === 'boolean' || value instanceof codec_js_1.UnsV2RawNumber)
-        return true;
-    if (typeof value === 'number')
-        return Number.isFinite(value);
-    if (typeof value !== 'object' || seen.has(value))
-        return false;
-    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
-        return false;
-    }
-    seen.add(value);
-    const valid = (Array.isArray(value) ? Array.from(value) : Object.values(value)).every(item => json(item, seen));
-    seen.delete(value);
-    return valid;
-}
-function definition(value) {
-    if (!record(value))
-        return false;
-    return ['code', 'name', 'description', 'contractVersion', 'status'].every(key => typeof value[key] === 'string') &&
-        value.code !== '' && value.contractVersion !== '' && record(value.inputSchema) && record(value.outputSchema) &&
-        ['read', 'write'].includes(value.sideEffect) &&
-        ['none', 'optional', 'required'].includes(value.idempotency) &&
-        typeof value.timeoutMs === 'number' && Number.isSafeInteger(value.timeoutMs) && value.timeoutMs > 0;
-}
-function runInfo(value) {
-    if (!record(value))
-        return {};
-    return {
-        runID: typeof value.runId === 'string' ? value.runId : undefined,
-        contractVersion: typeof value.contractVersion === 'string' ? value.contractVersion : undefined,
-        runStatus: typeof value.status === 'string' ? value.status : undefined,
-        replayed: typeof value.replayed === 'boolean' ? value.replayed : undefined,
-    };
-}
-class ControlsClient {
-    uns;
-    constructor(resolveClient = client_js_1.getClient, config = {}) {
-        this.uns = new client_js_2.UnsV2ClientCore(resolveClient, config);
-    }
-    async post(operation, body) {
-        try {
-            const response = await this.uns.call(operation, body);
-            return { value: response.data, status: 200 };
-        }
-        catch (error) {
-            if (!(error instanceof client_js_2.UnsV2Error))
-                throw error;
-            const info = {
-                ...runInfo(error.data), status: error.status,
-                errorCode: error.code.replace(/^UNS_V2_/, 'CONTROL_'),
-                requestId: error.requestId, execution: error.execution, retry: error.retry,
-                reason: error.reason, details: error.details, data: error.data,
-            };
-            if (error.outcomeUnknown)
-                throw new ControlResultUnknownError(info);
-            throw new ControlError(error.message, info);
-        }
-    }
-    /** Discover visible contracts; defaults and authorization are resolved by the server. */
-    async discover(options = {}) {
-        keys(options, ['page', 'size', 'search']);
-        if ((options.page !== undefined && (!Number.isSafeInteger(options.page) || options.page < 1)) ||
-            (options.size !== undefined && (!Number.isSafeInteger(options.size) || options.size < 1 || options.size > 200)) ||
-            (options.search !== undefined && typeof options.search !== 'string')) {
-            throw new TypeError('Tier0 SDK: invalid Control discovery options.');
-        }
-        const { value, status } = await this.post('controlDiscover', options);
-        if (!record(value) || !Number.isSafeInteger(value.total) || value.total < 0 ||
-            !Array.isArray(value.list) || !value.list.every(definition)) {
-            throw new ControlError('Invalid Control discovery response.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });
-        }
-        return { total: value.total, list: value.list };
-    }
-    use(selector) {
-        keys(selector, ['code']);
-        const code = selector.code;
-        if (typeof code !== 'string' || code.length > 128 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(code)) {
-            throw new TypeError('Tier0 SDK: invalid Control code.');
-        }
-        return {
-            describe: async () => {
-                const { value, status } = await this.post('controlDescribe', { code });
-                if (!definition(value) || value.code !== code) {
-                    throw new ControlError('Invalid Control description.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });
-                }
-                return value;
-            },
-            invoke: async (input, options = {}) => {
-                keys(options, ['idempotencyKey']);
-                const key = options.idempotencyKey;
-                if (key !== undefined && (typeof key !== 'string' || !key || key.trim() !== key || new TextEncoder().encode(key).length > 128)) {
-                    throw new TypeError('Tier0 SDK: invalid Control idempotency key.');
-                }
-                if (!json(input))
-                    throw new TypeError('Tier0 SDK: Control input must be JSON.');
-                const { value, status } = await this.post('controlInvoke', {
-                    code, input: input, ...(key === undefined ? {} : { idempotencyKey: key }),
-                });
-                if (!record(value) || value.code !== code || typeof value.contractVersion !== 'string' || !value.contractVersion ||
-                    !Object.prototype.hasOwnProperty.call(value, 'result') || typeof value.runId !== 'string' || !value.runId ||
-                    typeof value.status !== 'string' || !value.status || ['accepted', 'queued', 'pending', 'running'].includes(value.status) ||
-                    typeof value.replayed !== 'boolean') {
-                    throw new ControlResultUnknownError({ ...runInfo(value), status, errorCode: 'CONTROL_PROTOCOL_ERROR' });
-                }
-                return { code: value.code, contractVersion: value.contractVersion, result: value.result,
-                    runID: value.runId, status: value.status, replayed: value.replayed };
-            },
-        };
-    }
-}
-exports.ControlsClient = ControlsClient;
-/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */
-exports.controls = new ControlsClient();
-//# sourceMappingURL=controls.js.map

package/dist/cjs/controls.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"controls.js","sourceRoot":"","sources":["../../src/controls.ts"],"names":[],"mappings":"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","sourcesContent":["import { getClient, type HttpClient, type ClientConfig } from './openapi/client.js';\nimport { DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS, type CloudTransportConfig } from './cloud-transport.js';\nimport { UnsV2ClientCore, UnsV2Error, type UnsV2Execution, type UnsV2Retry } from './uns-v2/client.js';\nimport { UnsV2RawNumber } from './uns-v2/codec.js';\nimport type { UnsV2JSONValue, UnsV2Request } from './uns-v2/generated.js';\n\n/** Control convenience API over the canonical UNS v2 routes. Exact numbers are preserved. */\nexport type ControlJSON = UnsV2JSONValue;\n\nexport interface PublicControl {\n  code: string;\n  name: string;\n  description: string;\n  contractVersion: string;\n  inputSchema: Record<string, ControlJSON>;\n  outputSchema: Record<string, ControlJSON>;\n  sideEffect: 'read' | 'write';\n  idempotency: 'none' | 'optional' | 'required';\n  timeoutMs: number;\n  status: string;\n}\n\nexport interface ControlDiscoverOptions {\n  page?: number;\n  size?: number;\n  search?: string;\n}\n\nexport interface ControlDiscoverResponse {\n  total: number;\n  list: PublicControl[];\n}\n\n/** Shared HTTP settings. The server still resolves the Control binding and authorization. */\nexport interface ControlTransportConfig extends CloudTransportConfig {}\n\nexport interface CloudClientConfig extends ClientConfig, ControlTransportConfig {}\n\nexport const DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS;\n\nexport interface ControlInvokeOptions {\n  /** Stable caller-owned key for one business intent, at most 128 UTF-8 bytes. Never generated or retried by the SDK. */\n  idempotencyKey?: string;\n}\n\nexport interface ControlInvokeResponse<Result = ControlJSON> {\n  code: string;\n  contractVersion: string;\n  result: Result;\n  runID: string;\n  status: string;\n  /** True only when the server explicitly reports an idempotent replay. */\n  replayed: boolean;\n}\n\nexport interface ControlErrorInfo {\n  /** HTTP status, absent when no HTTP response was received. */\n  status?: number;\n  /** Canonical UNS error.code, or an SDK-local CONTROL_* transport/protocol code. */\n  errorCode: string;\n  runID?: string;\n  contractVersion?: string;\n  runStatus?: string;\n  replayed?: boolean;\n  requestId?: string;\n  execution?: UnsV2Execution;\n  retry?: UnsV2Retry;\n  reason?: string;\n  details?: Record<string, unknown>[];\n  data?: unknown;\n}\n\n/** No Control error is automatically retried, including authentication failures. */\nexport class ControlError extends Error {\n  readonly status?: number;\n  readonly errorCode: string;\n  readonly runID?: string;\n  readonly contractVersion?: string;\n  readonly runStatus?: string;\n  readonly replayed?: boolean;\n  readonly requestId?: string;\n  readonly execution?: UnsV2Execution;\n  readonly retry?: UnsV2Retry;\n  readonly reason?: string;\n  readonly details?: Record<string, unknown>[];\n  readonly data?: unknown;\n  readonly retryable = false;\n\n  constructor(message: string, info: ControlErrorInfo) {\n    super(message);\n    this.name = 'ControlError';\n    this.status = info.status;\n    this.errorCode = info.errorCode;\n    this.runID = info.runID;\n    this.contractVersion = info.contractVersion;\n    this.runStatus = info.runStatus;\n    this.replayed = info.replayed;\n    this.requestId = info.requestId;\n    this.execution = info.execution;\n    this.retry = info.retry;\n    this.reason = info.reason;\n    this.details = info.details;\n    this.data = info.data;\n  }\n}\n\n/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */\nexport class ControlResultUnknownError extends ControlError {\n  readonly outcomeUnknown = true;\n\n  constructor(info: ControlErrorInfo) {\n    super('Control result is unknown; execution may have occurred. Do not automatically retry.', info);\n    this.name = 'ControlResultUnknownError';\n  }\n}\n\nfunction record(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nfunction keys(value: unknown, allowed: string[]): void {\n  if (!record(value) || Reflect.ownKeys(value).some(key => typeof key !== 'string' || !allowed.includes(key))) {\n    throw new TypeError('Tier0 SDK: unsupported Control option.');\n  }\n}\n\nfunction json(value: unknown, seen = new Set<unknown>()): boolean {\n  if (value === null || typeof value === 'string' || typeof value === 'boolean' || value instanceof UnsV2RawNumber) return true;\n  if (typeof value === 'number') return Number.isFinite(value);\n  if (typeof value !== 'object' || seen.has(value)) return false;\n  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {\n    return false;\n  }\n  seen.add(value);\n  const valid = (Array.isArray(value) ? Array.from(value) : Object.values(value)).every(item => json(item, seen));\n  seen.delete(value);\n  return valid;\n}\n\nfunction definition(value: unknown): value is PublicControl {\n  if (!record(value)) return false;\n  return ['code', 'name', 'description', 'contractVersion', 'status'].every(key => typeof value[key] === 'string') &&\n    value.code !== '' && value.contractVersion !== '' && record(value.inputSchema) && record(value.outputSchema) &&\n    ['read', 'write'].includes(value.sideEffect as string) &&\n    ['none', 'optional', 'required'].includes(value.idempotency as string) &&\n    typeof value.timeoutMs === 'number' && Number.isSafeInteger(value.timeoutMs) && value.timeoutMs > 0;\n}\n\nfunction runInfo(value: unknown): Partial<ControlErrorInfo> {\n  if (!record(value)) return {};\n  return {\n    runID: typeof value.runId === 'string' ? value.runId : undefined,\n    contractVersion: typeof value.contractVersion === 'string' ? value.contractVersion : undefined,\n    runStatus: typeof value.status === 'string' ? value.status : undefined,\n    replayed: typeof value.replayed === 'boolean' ? value.replayed : undefined,\n  };\n}\n\nexport interface ControlHandle<Input = ControlJSON, Result = ControlJSON> {\n  describe(): Promise<PublicControl>;\n  /**\n   * One POST only. Input is opaque business JSON, including fields named streamId,\n   * entryId, deploymentVersion or timeoutMs. Only the server chooses binding/version/timeout.\n   * Generic types are caller assertions; the server validates the contract schemas.\n   */\n  invoke(input: Input, options?: ControlInvokeOptions): Promise<ControlInvokeResponse<Result>>;\n}\n\nexport class ControlsClient {\n  private readonly uns: UnsV2ClientCore;\n\n  constructor(resolveClient: () => HttpClient = getClient, config: ControlTransportConfig = {}) {\n    this.uns = new UnsV2ClientCore(resolveClient, config);\n  }\n\n  private async post<Name extends 'controlDiscover' | 'controlDescribe' | 'controlInvoke'>(\n    operation: Name, body: UnsV2Request<Name>,\n  ): Promise<{ value: unknown; status: number }> {\n    try {\n      const response = await this.uns.call(operation, body);\n      return { value: response.data, status: 200 };\n    } catch (error) {\n      if (!(error instanceof UnsV2Error)) throw error;\n      const info: ControlErrorInfo = {\n        ...runInfo(error.data), status: error.status,\n        errorCode: error.code.replace(/^UNS_V2_/, 'CONTROL_'),\n        requestId: error.requestId, execution: error.execution, retry: error.retry,\n        reason: error.reason, details: error.details, data: error.data,\n      };\n      if (error.outcomeUnknown) throw new ControlResultUnknownError(info);\n      throw new ControlError(error.message, info);\n    }\n  }\n\n  /** Discover visible contracts; defaults and authorization are resolved by the server. */\n  async discover(options: ControlDiscoverOptions = {}): Promise<ControlDiscoverResponse> {\n    keys(options, ['page', 'size', 'search']);\n    if ((options.page !== undefined && (!Number.isSafeInteger(options.page) || options.page < 1)) ||\n        (options.size !== undefined && (!Number.isSafeInteger(options.size) || options.size < 1 || options.size > 200)) ||\n        (options.search !== undefined && typeof options.search !== 'string')) {\n      throw new TypeError('Tier0 SDK: invalid Control discovery options.');\n    }\n    const { value, status } = await this.post('controlDiscover', options);\n    if (!record(value) || !Number.isSafeInteger(value.total) || (value.total as number) < 0 ||\n        !Array.isArray(value.list) || !value.list.every(definition)) {\n      throw new ControlError('Invalid Control discovery response.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });\n    }\n    return { total: value.total as number, list: value.list as PublicControl[] };\n  }\n\n  use<Input = ControlJSON, Result = ControlJSON>(selector: { code: string }): ControlHandle<Input, Result> {\n    keys(selector, ['code']);\n    const code = selector.code;\n    if (typeof code !== 'string' || code.length > 128 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(code)) {\n      throw new TypeError('Tier0 SDK: invalid Control code.');\n    }\n    return {\n      describe: async () => {\n        const { value, status } = await this.post('controlDescribe', { code });\n        if (!definition(value) || value.code !== code) {\n          throw new ControlError('Invalid Control description.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });\n        }\n        return value;\n      },\n      invoke: async (input, options = {}) => {\n        keys(options, ['idempotencyKey']);\n        const key = options.idempotencyKey;\n        if (key !== undefined && (typeof key !== 'string' || !key || key.trim() !== key || new TextEncoder().encode(key).length > 128)) {\n          throw new TypeError('Tier0 SDK: invalid Control idempotency key.');\n        }\n        if (!json(input)) throw new TypeError('Tier0 SDK: Control input must be JSON.');\n        const { value, status } = await this.post('controlInvoke', {\n          code, input: input as ControlJSON, ...(key === undefined ? {} : { idempotencyKey: key }),\n        });\n        if (!record(value) || value.code !== code || typeof value.contractVersion !== 'string' || !value.contractVersion ||\n            !Object.prototype.hasOwnProperty.call(value, 'result') || typeof value.runId !== 'string' || !value.runId ||\n            typeof value.status !== 'string' || !value.status || ['accepted', 'queued', 'pending', 'running'].includes(value.status) ||\n            typeof value.replayed !== 'boolean') {\n          throw new ControlResultUnknownError({ ...runInfo(value), status, errorCode: 'CONTROL_PROTOCOL_ERROR' });\n        }\n        return { code: value.code, contractVersion: value.contractVersion, result: value.result as Result,\n          runID: value.runId, status: value.status, replayed: value.replayed };\n      },\n    };\n  }\n}\n\n/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */\nexport const controls = new ControlsClient();\n"]}