@tier0/sdk-v2 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FREEZONEX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Source attribution
+
+This SDK is distributed under the MIT license in LICENSE.
+
+The UNS lossless codec, transport safeguards, Control and capability clients, MQTT implementation, App request identity verifier, and selected regression tests were adapted from FREEZONEX/Tier0-sdk at commit `3e43f33f4d13729e61b3d7e9bd8225a42f6843a8` (MIT). The original copyright notice is retained.
+
+Public API contracts were obtained from FREEZONEX/Tier0-Backend at the revision pinned in `contracts/upstream.json`. The bundled App request identity contract was inherited from the same SDK revision; its upstream contract digest is preserved in the generated source. This provenance does not establish deployment or interoperability with a later gateway revision.

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# @tier0/sdk-v2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tier0 云端新架构的独立 TypeScript / JavaScript SDK。新仓库、新 npm 包，不覆盖 `@tier0/sdk`。
+
+当前版本 `0.1.0` 是待联调的首版源码，尚未发布 npm，也不表示开发环境已部署对应后端。要求 Node.js 20.19+。浏览器 HTTP、MQTT、React、Vue 和服务端身份验签分别提供独立入口。
+
+## 安装与初始化
+
+首发前在本仓库运行 `npm ci`、`npm run check`、`npm pack`，业务项目安装生成的 `.tgz`。发布后使用：
+
+```sh
+npm install @tier0/sdk-v2
+```
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+// 服务端环境注入 TIER0_API_HOST 和 TIER0_API_KEY。
+const tier0 = createClient();
+const user = await tier0.system.whoami();
+const platform = await tier0.system.info();
+const capabilities = await tier0.capabilities.discover();
+```
+
+也可显式配置 `{ apiHost, apiKey, transportTimeoutMs, fetch }`，或提供 `getApiHost` / `getApiKey` 回调。裸域名默认使用 HTTPS；本地 HTTP 测试请显式写 `http://127.0.0.1:端口`。不自动向浏览器注入或读取 `VITE_` API Key。
+
+`createClient()` 实例之间不共享配置；推荐在一个稳定身份的服务生命周期内复用实例。员工数据委托必须为每个请求创建新实例，传入受信网关的 `unsV2AppDataSubject`。App Key 只代表 App，不能替代当前用户身份，也不能下发到浏览器。浏览器页面应调用自己的服务端 API。
+
+## 能力与入口
+
+| 入口 | 能力 |
+| --- | --- |
+| `tier0.source` | 数据源、连接文档、影响分析、版本历史与运行观测 |
+| `tier0.stream` | Runtime programs、原生文档、校验、部署、回滚与运行记录 |
+| `tier0.uns` | 目录、Topic、Collection、Record、Sample、事务与 App 数据上下文 |
+| `tier0.system` | `whoami()`、`info()` |
+| `tier0.members` | `listWorkspace()` 用于 Workspace 级成员选择；`listApp({ appId })` 查询能使用指定 App 的成员 |
+| `tier0.notifications` | `send()`、`get()` |
+| `tier0.files` | `upload()`、`uploadMultipart()`、`url()`、`download()`、`delete()`、`multipart` 原子接口 |
+| `tier0.mqttAuth` | 创建、删除 MQTT 凭证 |
+| `tier0.agent` | `analyses`、`canvases`、`cards`、`jobs`、`jobRuns`、`library`、`nodes`、`relations`、`results` |
+| `tier0.capabilities` | 当前凭证可见的能力发现；就绪状态由服务端判断 |
+| `tier0.controls` | Control 发现、描述、执行及结果未知错误 |
+| `tier0.api` | 51 个普通 OpenAPI 的完整生成接口；通常优先使用上面的领域入口 |
+| `@tier0/sdk-v2/mq` | MQTT WebSocket 客户端与 broker 地址工具；不进入根入口依赖图 |
+| `@tier0/sdk-v2/source` | `createSourceClient()`，独立 Source 客户端 |
+| `@tier0/sdk-v2/stream` | `createStreamClient()`，独立 Stream 客户端 |
+| `@tier0/sdk-v2/react` | `useTier0Query()`、`useTier0Mutation()`，需要 React 和 TanStack Query |
+| `@tier0/sdk-v2/vue` | `useTier0Request()`，需要 Vue 3 |
+| `@tier0/sdk-v2/server` | `createCloudAppRequestVerifier()`，仅服务端加载 `node:crypto` |
+| `@tier0/sdk-v2/data` | App 数据层：`defineCollection()` 声明集合、`createDataClient()` 首次访问时 ensure，Mongo 风格读写、原子批量与 `transact`、员工数据主体透传；仅服务端，需要 `zod` 4 |
+| `@tier0/sdk-v2/data/define` | 集合声明与类型：`defineCollection()`、`Doc` / `NewDoc` 等、`compileCollection()`、`validateDocument()`；可进浏览器包，组件和 route 的客户端代码只从这里取声明和类型 |
+
+不保留 UNS v1、旧 Flow、`getCurrentProjectId()`、project 成员查询或 `/gw/reload`。Workspace 成员不等于能使用某个 App 的成员，不可用前者在客户端猜测 App 权限。
+
+## Source、Stream 与 UNS 分域
+
+Source 负责连接外部系统，Stream 负责处理与运行，UNS 负责命名空间与业务数据。共用底层 106 个公开生成操作，业务入口按领域组织；Control 使用 `tier0.controls` 的专属契约。
+
+```ts
+const sources = await tier0.source.documents.list({ page: 1, size: 20 });
+const programs = await tier0.stream.programs.list({ page: 1, size: 20 });
+const runtime = await tier0.stream.runtime.capabilities({});
+```
+
+Source/Stream 仍保留 `{ code, msg, requestId, data }` 响应以及 `UnsV2Error` 错误类型。`source.documents` 是云端原生文档，`source.create/validate` 等是通用投影；`stream.programs` 与 `stream.documents` 使用不同文档结构，不可混用。保存、部署、运行成功分别判断。
+
+从最初提交迁移：`uns.sourceList` → `source.list`；`uns.sourceDocumentGet` → `source.documents.get`；`uns.streamProgramDeploy` → `stream.programs.deploy`；`uns.streamDocumentValidate` → `stream.documents.validate`。这些管理方法已移出主入口的 `uns`。底层 `createUnsV2Client()` 仍提供完整生成契约供契约工具使用；数据专用客户端可用 `createUnsDataClient()`。
+
+随包提供 12 个可独立发现的 Skill，包含完整流程、参数边界、错误处理与可类型检查的示例：[入口](skills/tier0-sdk-v2/SKILL.md)、[Source](skills/tier0-sdk-v2-source/SKILL.md)、[Stream](skills/tier0-sdk-v2-stream/SKILL.md)、[UNS](skills/tier0-sdk-v2-uns/SKILL.md)、[通知](skills/tier0-sdk-v2-notifications/SKILL.md)、[系统](skills/tier0-sdk-v2-system/SKILL.md)、[文件](skills/tier0-sdk-v2-files/SKILL.md)、[MQTT](skills/tier0-sdk-v2-mq/SKILL.md)、[成员](skills/tier0-sdk-v2-members/SKILL.md)、[Controls](skills/tier0-sdk-v2-controls/SKILL.md)、[Agent](skills/tier0-sdk-v2-agent/SKILL.md)、[App 数据](skills/tier0-sdk-v2-data/SKILL.md)。复杂流程的参考文档随 Skill 一起打包。
+
+## UNS 数据访问
+
+```ts
+const context = await tier0.uns.dataAppContext({});
+const page = await tier0.uns.recordFind({ collectionId: 'orders', limit: 20 });
+const records = page.data;
+
+const controller = new AbortController();
+await tier0.uns.recordFind(
+  { collectionId: 'orders', limit: 20 },
+  { signal: controller.signal },
+);
+```
+
+实际集合 ID 和有效权限从平台配置/数据上下文取得。管理操作中，App 凭证只能调用本 App 集合的 `appCollectionsEnsure` / `appCollectionsSchemaReplace` / `appCollectionsArchive` / `appCollectionsRestore`；SDK 中存在 `collectionCreate` 等其他管理方法，不表示 App 凭证有对应权限。App 数据授权 `appDataPolicyGet` / `appDataPolicyUpdate` 的调用方必须是：持有 `uns.write` 的登录会话、持有 `uns.write` 且 full_access、不绑定 App 的 personal / agent Key，或治理会话；运行时 App 凭证不能管理授权。Core-only 后台接口不导出到公开 SDK。
+
+UNS 保留 `{ code, msg, requestId, data }` 完整响应。普通 v1 包装接口返回已解包的 `data`，通知/Control/能力发现返回服务端直接对象。业务错误即使 HTTP 为 200 也会抛出 `ApiError`。
+
+`int64` 和普通 v1 整数字段使用 `number | bigint`：安全范围内返回 number，超出范围返回 bigint。UNS 任意 JSON 中无法无损表示的数字用 `UnsV2RawNumber`；传回 SDK 可保持原值。对外输出 JSON 时自行确定 bigint/精确数字的表示，不要直接 `JSON.stringify` 包含这些值的对象。
+
+HTTP 操作不自动重试。`UnsV2OutcomeUnknownError`、`ControlResultUnknownError` 或 `ApiError.outcomeUnknown` 表示写操作可能已执行；先查询结果/作业，按业务意图保留原幂等键，不自动生成新键重放。查询与写入均可受配置超时约束。
+
+## 通知
+
+```ts
+import { getCurrentAppId } from '@tier0/sdk-v2';
+
+await tier0.notifications.send({
+  recipientUserId: '目标用户ID',
+  type: 'business',
+  title: '工单已完成',
+  content: '请查看处理结果。',
+  idempotencyKey: 'work-order-123-completed',
+  sender: { type: 'app', id: getCurrentAppId() },
+});
+```
+
+不传 `channels` 时发送 `['web', 'mobile']`；`web` 包含 Web 与 Desktop；`[]` 只创建站内信。重复值去重，显式单渠道不补齐，不接受 `desktop`。App 身份读取平台注入的真实 `APP_ID`，不依赖 Folder 或 project。
+
+## 文件
+
+```ts
+const saved = await tier0.files.upload(new File(['report'], 'report.txt'));
+const stableReference = saved.filePath;
+const { fileUrl } = await tier0.files.url({ filePath: stableReference });
+const response = await tier0.files.download({ filePath: stableReference });
+const bytes = await response.arrayBuffer();
+```
+
+保存 `filePath`，不把临时签名地址当作持久化引用。上传由平台签发地址后直传对象存储，平台 API Key 不传到存储域名；下载先获取签名地址，再匿名获取文件，避免认证重定向泄漏凭证。
+
+超过 100 MiB 自动使用分片上传，也可调用 `uploadMultipart(file, { partSize, signal, onProgress })`。首版顺序上传分片，不自动重试。中断后 `MultipartUploadError.session` 保留 uploadId、fileKey、已完成 parts 和 `completionAttempted`，可以通过 `files.multipart` 完成或终止；尝试过 complete 后必须先核对结果。未实现自动断点续传。
+
+返回的下载 `Response` 由调用方消费；文件传输配置超时约束取得响应头的阶段，后续流式读取由调用方管理。所有业务附件、头像、导入/导出文件使用平台文件存储，不以 App 本地目录作为持久化存储。
+
+## MQTT
+
+```ts
+import { Tier0MQClient, toWebSocketUrl } from '@tier0/sdk-v2/mq';
+
+const info = await tier0.system.info();
+const credentials = await tier0.mqttAuth.create({ name: 'integration-client' });
+const mq = new Tier0MQClient({
+  host: toWebSocketUrl(info.mqttBroker),
+  clientId: credentials.clientID,
+  username: credentials.username,
+  password: credentials.password,
+});
+await mq.connect();
+mq.subscribe('平台授权的主题', (_topic, payload) => { /* 处理消息 */ });
+```
+
+完整凭证只在创建时返回一次。也支持从编码 Workspace 的平台 API Key 推导 MQTT 身份；无法解析的 Key 会拒绝连接，不回退到 Enterprise 身份。MQTT 自身的连接恢复/QoS 语义与 HTTP 的“不自动重试写入”是不同机制。
+
+## React / Vue
+
+```ts
+import { useTier0Query, useTier0Mutation } from '@tier0/sdk-v2/react';
+
+const orders = useTier0Query(tier0, ['orders'], (client, signal) =>
+  client.uns.recordFind({ collectionId: 'orders' }, { signal }));
+const send = useTier0Mutation(tier0, (client, body: Parameters<typeof tier0.notifications.send>[0]) =>
+  client.notifications.send(body));
+```
+
+React 需要 `QueryClientProvider`。保持客户端实例稳定；查询缓存按实例隔离，不跨凭证共享。查询 hook 只用于读取，写操作用 mutation。框架入口不会自动重试。
+
+```ts
+import { useTier0Request } from '@tier0/sdk-v2/vue';
+const orders = useTier0Request(tier0, (client, collectionId: string, signal) =>
+  client.uns.recordFind({ collectionId }, { signal }));
+await orders.execute('orders');
+```
+
+Vue 由 `execute()` 显式执行，后发请求的结果优先；取消不表示服务端写入已撤销。
+
+## 契约更新与验证
+
+上游：`FREEZONEX/Tier0-Backend`，固定提交 `fb35598ae8404e1a64bdc8a500341f12aeff2744`。`contracts/upstream.json` 记录来源和 SHA-256。
+
+```sh
+npm ci
+npm run check
+
+# 更新时显式提供后端 checkout 与已提交版本；不会自动读取工作区未提交修改。
+npm run sync:contracts -- ../Tier0-Backend <commit>
+npm run generate
+npm run check
+```
+
+v1 来自网关 Swagger，并按实际 handler 补齐响应外层；UNS 来自 `contract_generated.go#ContractJSON` 中已经应用 Cloud 扩展的契约，结合 manifest/registry 生成。不能直接使用仍含 Enterprise 基础操作的 `share/unscontract/contract.json` 作为最终云端契约。
+
+`npm run check` 包含契约一致性、Skill 注册及递归引用检查、所有 Skill TypeScript 示例的源码/安装包类型校验、单元和本地 HTTP 测试、ESM/CJS 构建、实际 npm 包安装、浏览器打包及导入验证。完整行为测试还会在独立 consumer 中对已安装的 `.tgz` 再跑一遍，导入目标严格指向包内 `dist`；包内调试映射包含源内容。当前 652 项测试包含全部 157 个公开操作的路由检查。路由检查使用本地 HTTP fixture，不等于每个操作的业务验收。
+
+`tests/skill-workflows.test.ts` 直接提取 Markdown 示例，验证 Source/Stream/UNS 的创建、查询、修改、删除或归档恢复，影响分页和结果未知分支，以及通知请求、状态查询和成员展示。默认检查不调用线上接口。
+
+真实环境验收脚本使用刚安装的包，先通过 `whoami` 核对 Workspace，再执行选定操作。`TIER0_API_HOST` 必须指向 API 网关（开发环境为 `https://api-dev.tier0.cn`，不是网页域名 `dev.tier0.cn`），`TIER0_API_KEY` 由当前进程环境提供，不放进命令行参数或版本库。
+
+```sh
+# consumer 路径使用 npm run check 最后输出的 .tmp/package-check-* 目录。
+node scripts/check-live-readonly.mjs <consumer> <workspaceId> .tmp/live-readonly.json
+
+# 仅在已授权的测试 Workspace 执行；会创建、修改、归档/删除本次测试资源。
+# 可用 TIER0_TEST_DOMAINS 选择 source,stream,uns,files；追加 extended 扩展 UNS 验收。
+node scripts/check-live-workflows.mjs <consumer> <workspaceId> .tmp/live-workflows.json --write-test-fixtures
+node scripts/check-live-transports.mjs <consumer> <workspaceId> .tmp/live-transports.json --write-test-fixtures
+```
+
+写入验收不发布 Stream、不启用 Source、不发送通知。归档资源保留正常产品恢复能力；报告区分通过、服务端拒绝和未验证范围。分片上传失败会保留错误原因，确认尚未尝试 complete 时清理本次会话；完成结果未知时先对账。完整结果见 [2026-10-22 验收报告](docs/acceptance-2026-10-22.md)。
+
+首发前仍需：解决验收报告中的阻断并补齐未验收范围、App 脚手架切换精确依赖 `"@tier0/sdk-v2": "0.1.0"`、新 Skill 上传和 npm 发布授权。

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

@@ -0,0 +1,22 @@
+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"];
+};

package/dist/cjs/app-identity-contract.generated.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_REQUEST_IDENTITY_CONTRACT = void 0;
+// Generated from SWE gatewayheader/app-request-identity.v1.json; do not edit.
+// Source SHA-256: ac5ec2efb882395e63a46c9ec479de16c09943b88fc0bd906dd77c7f9f4bfaa3
+exports.APP_REQUEST_IDENTITY_CONTRACT = {
+    "version": "tier0.app-request-identity/v1",
+    "header": "X-Tier0-App-Identity",
+    "type": "tier0-app-request+jwt",
+    "algorithm": "EdDSA",
+    "issuer": "tier0-app-gateway",
+    "audience": "tier0-app-runtime",
+    "maxTokenBytes": 8192,
+    "maxBodyBytes": 65536,
+    "maxURIBytes": 8192,
+    "maxTTLSeconds": 30,
+    "clockSkewSeconds": 5,
+    "maxRoles": 32,
+    "maxRoleBytes": 128,
+    "maxKeys": 8,
+    "keyIDPattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$",
+    "appIDPattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+    "requiredClaims": [
+        "ver",
+        "iss",
+        "aud",
+        "sub",
+        "workspaceID",
+        "appID",
+        "method",
+        "requestURI",
+        "bodySHA256",
+        "iat",
+        "exp",
+        "jti",
+        "roles"
+    ],
+    "methodPattern": "^[A-Z]{1,16}$",
+    "requiredHeaderFields": [
+        "alg",
+        "typ",
+        "kid"
+    ],
+    "publicKeyFields": [
+        "kty",
+        "crv",
+        "x",
+        "kid"
+    ]
+};
+//# sourceMappingURL=app-identity-contract.generated.js.map

package/dist/cjs/app-identity-contract.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-identity-contract.generated.js","sourceRoot":"","sources":["../../src/app-identity-contract.generated.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AAC9E,mFAAmF;AACtE,QAAA,6BAA6B,GAAG;IAC3C,SAAS,EAAE,+BAA+B;IAC1C,QAAQ,EAAE,sBAAsB;IAChC,MAAM,EAAE,uBAAuB;IAC/B,WAAW,EAAE,OAAO;IACpB,QAAQ,EAAE,mBAAmB;IAC7B,UAAU,EAAE,mBAAmB;IAC/B,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,EAAE;IACnB,kBAAkB,EAAE,CAAC;IACrB,UAAU,EAAE,EAAE;IACd,cAAc,EAAE,GAAG;IACnB,SAAS,EAAE,CAAC;IACZ,cAAc,EAAE,mCAAmC;IACnD,cAAc,EAAE,2EAA2E;IAC3F,gBAAgB,EAAE;QAChB,KAAK;QACL,KAAK;QACL,KAAK;QACL,KAAK;QACL,aAAa;QACb,OAAO;QACP,QAAQ;QACR,YAAY;QACZ,YAAY;QACZ,KAAK;QACL,KAAK;QACL,KAAK;QACL,OAAO;KACR;IACD,eAAe,EAAE,eAAe;IAChC,sBAAsB,EAAE;QACtB,KAAK;QACL,KAAK;QACL,KAAK;KACN;IACD,iBAAiB,EAAE;QACjB,KAAK;QACL,KAAK;QACL,GAAG;QACH,KAAK;KACN;CACO,CAAC","sourcesContent":["// Generated from SWE gatewayheader/app-request-identity.v1.json; do not edit.\r\n// Source SHA-256: ac5ec2efb882395e63a46c9ec479de16c09943b88fc0bd906dd77c7f9f4bfaa3\r\nexport const APP_REQUEST_IDENTITY_CONTRACT = {\r\n  \"version\": \"tier0.app-request-identity/v1\",\r\n  \"header\": \"X-Tier0-App-Identity\",\r\n  \"type\": \"tier0-app-request+jwt\",\r\n  \"algorithm\": \"EdDSA\",\r\n  \"issuer\": \"tier0-app-gateway\",\r\n  \"audience\": \"tier0-app-runtime\",\r\n  \"maxTokenBytes\": 8192,\r\n  \"maxBodyBytes\": 65536,\r\n  \"maxURIBytes\": 8192,\r\n  \"maxTTLSeconds\": 30,\r\n  \"clockSkewSeconds\": 5,\r\n  \"maxRoles\": 32,\r\n  \"maxRoleBytes\": 128,\r\n  \"maxKeys\": 8,\r\n  \"keyIDPattern\": \"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$\",\r\n  \"appIDPattern\": \"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$\",\r\n  \"requiredClaims\": [\r\n    \"ver\",\r\n    \"iss\",\r\n    \"aud\",\r\n    \"sub\",\r\n    \"workspaceID\",\r\n    \"appID\",\r\n    \"method\",\r\n    \"requestURI\",\r\n    \"bodySHA256\",\r\n    \"iat\",\r\n    \"exp\",\r\n    \"jti\",\r\n    \"roles\"\r\n  ],\r\n  \"methodPattern\": \"^[A-Z]{1,16}$\",\r\n  \"requiredHeaderFields\": [\r\n    \"alg\",\r\n    \"typ\",\r\n    \"kid\"\r\n  ],\r\n  \"publicKeyFields\": [\r\n    \"kty\",\r\n    \"crv\",\r\n    \"x\",\r\n    \"kid\"\r\n  ]\r\n} as const;\r\n"]}

package/dist/cjs/capabilities.d.ts

@@ -0,0 +1,54 @@
+import { type CloudTransportConfig } from './cloud-transport.js';
+import { type HttpClient } from './openapi/client.js';
+export type CapabilityCode = 'namespace.v2' | 'source.v1' | 'stream.v2' | 'control.v1' | 'control.invoke.v1';
+export type CapabilityState = 'disabled' | 'not_supported' | 'unavailable' | 'readiness_unknown' | 'ready';
+export type CapabilityAvailability = 'unavailable' | 'unknown' | 'available';
+export interface PublicCapability {
+    code: CapabilityCode;
+    /** Public release and workspace gates; does not establish runtime readiness. */
+    releaseEnabled: boolean;
+    /** Server-assessed implementation/readiness, never inferred from releaseEnabled. */
+    enabled: boolean;
+    /** Authorization summary, not a grant for every individual Control code. */
+    allowed: boolean;
+    state: CapabilityState;
+    /** Not device online status or execution/ACK confirmation. */
+    availability: CapabilityAvailability;
+    contractVersions: string[];
+}
+export interface CapabilityDeprecation {
+    contract: string;
+    replacement?: string;
+    sunsetAt?: string;
+}
+export interface CapabilityDiscoverResponse {
+    product: 'cloud';
+    /** Trusted server configuration only; absent when unconfigured. */
+    productVersion?: string;
+    contractVersion: '1.0';
+    apiContractVersions: string[];
+    interpreterContractVersions: string[];
+    /** Public SDK contract labels, not npm package versions. */
+    sdkContractVersions: string[];
+    capabilities: PublicCapability[];
+    deprecations: CapabilityDeprecation[];
+}
+export interface CapabilityErrorInfo {
+    status?: number;
+    /** Gateway string code (including unknown future codes), or an SDK-local CAPABILITY_* code. */
+    errorCode: string;
+}
+export declare class CapabilityError extends Error {
+    readonly status?: number;
+    readonly errorCode: string;
+    readonly retryable = false;
+    constructor(message: string, info: CapabilityErrorInfo);
+}
+export declare class CapabilitiesClient {
+    private readonly transport;
+    constructor(resolveClient?: () => HttpClient, config?: CloudTransportConfig);
+    /** Workspace comes exclusively from the authenticated key. One POST, no automatic retries or caching. */
+    discover(): Promise<CapabilityDiscoverResponse>;
+}
+/** Uses configureClient()/runtime environment, resolving the host and workspace key on every call. */
+export declare const capabilities: CapabilitiesClient;

package/dist/cjs/capabilities.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilities = exports.CapabilitiesClient = exports.CapabilityError = void 0;
+const cloud_transport_js_1 = require("./cloud-transport.js");
+const client_js_1 = require("./openapi/client.js");
+class CapabilityError extends Error {
+    status;
+    errorCode;
+    retryable = false;
+    constructor(message, info) {
+        super(message);
+        this.name = 'CapabilityError';
+        this.status = info.status;
+        this.errorCode = info.errorCode;
+    }
+}
+exports.CapabilityError = CapabilityError;
+const contracts = {
+    'namespace.v2': ['openapi/v2'],
+    'source.v1': ['openapi/v1'],
+    'stream.v2': ['tier0-stream/v2'],
+    'control.v1': ['openapi/v1', 'control/v1'],
+    'control.invoke.v1': ['openapi/v1', 'tier0-stream/v2', 'control/v1'],
+};
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function strings(value) {
+    return Array.isArray(value) && value.every(text) && new Set(value).size === value.length;
+}
+/** Validate and explicitly project the frozen contract; unknown capabilities/extension fields are ignored. */
+function discovery(value, status) {
+    const fail = (version = false) => {
+        throw new CapabilityError(version ? 'Unsupported capability contract version.' : 'Invalid capability discovery response.', {
+            status, errorCode: version ? 'CAPABILITY_UNSUPPORTED_VERSION' : 'CAPABILITY_PROTOCOL_ERROR',
+        });
+    };
+    if (!record(value))
+        return fail();
+    if (!text(value.product) || !text(value.contractVersion) ||
+        !strings(value.apiContractVersions) || !strings(value.interpreterContractVersions) || !strings(value.sdkContractVersions) ||
+        !Array.isArray(value.capabilities) || !Array.isArray(value.deprecations) ||
+        (value.productVersion !== undefined && !text(value.productVersion)))
+        return fail();
+    if (value.product !== 'cloud' || value.contractVersion !== '1.0' ||
+        !value.apiContractVersions.includes('openapi/v1') ||
+        !value.interpreterContractVersions.includes('tier0-stream/v2') ||
+        !value.sdkContractVersions.includes('control/v1'))
+        return fail(true);
+    const capabilities = [];
+    const seen = new Set();
+    for (const item of value.capabilities) {
+        if (!record(item) || !text(item.code))
+            return fail();
+        if (!Object.prototype.hasOwnProperty.call(contracts, item.code))
+            continue;
+        const code = item.code;
+        if (seen.has(code))
+            return fail();
+        seen.add(code);
+        if (typeof item.releaseEnabled !== 'boolean' || typeof item.enabled !== 'boolean' || typeof item.allowed !== 'boolean' ||
+            !['disabled', 'not_supported', 'unavailable', 'readiness_unknown', 'ready'].includes(item.state) ||
+            !['unavailable', 'unknown', 'available'].includes(item.availability) || !strings(item.contractVersions))
+            return fail();
+        if (contracts[code].some(version => !item.contractVersions.includes(version) ||
+            (version.startsWith('openapi/') && !value.apiContractVersions.includes(version))))
+            return fail(true);
+        const ready = item.state === 'ready';
+        const expectedAvailability = ready ? 'available' : item.state === 'readiness_unknown' ? 'unknown' : 'unavailable';
+        if (item.enabled !== ready || item.availability !== expectedAvailability ||
+            (ready && (!item.releaseEnabled || !item.allowed)) ||
+            (item.state === 'disabled' ? item.releaseEnabled : !item.releaseEnabled))
+            return fail();
+        capabilities.push({
+            code, releaseEnabled: item.releaseEnabled, enabled: item.enabled, allowed: item.allowed,
+            state: item.state, availability: item.availability,
+            contractVersions: [...item.contractVersions],
+        });
+    }
+    const deprecations = [];
+    for (const item of value.deprecations) {
+        if (!record(item) || !text(item.contract) ||
+            (item.replacement !== undefined && !text(item.replacement)) ||
+            (item.sunsetAt !== undefined && !text(item.sunsetAt)))
+            return fail();
+        deprecations.push({ contract: item.contract,
+            ...(item.replacement === undefined ? {} : { replacement: item.replacement }),
+            ...(item.sunsetAt === undefined ? {} : { sunsetAt: item.sunsetAt }),
+        });
+    }
+    return {
+        product: 'cloud', ...(value.productVersion === undefined ? {} : { productVersion: value.productVersion }),
+        contractVersion: '1.0', apiContractVersions: [...value.apiContractVersions],
+        interpreterContractVersions: [...value.interpreterContractVersions], sdkContractVersions: [...value.sdkContractVersions],
+        capabilities, deprecations,
+    };
+}
+class CapabilitiesClient {
+    transport;
+    constructor(resolveClient = client_js_1.getClient, config = {}) {
+        this.transport = new cloud_transport_js_1.CloudTransport(resolveClient, config);
+    }
+    /** Workspace comes exclusively from the authenticated key. One POST, no automatic retries or caching. */
+    async discover() {
+        if (arguments.length !== 0)
+            throw new TypeError('Tier0 SDK: capability discovery accepts no arguments.');
+        let response;
+        try {
+            response = await this.transport.post('/openapi/v1/capabilities/discover', {});
+        }
+        catch (error) {
+            if (!(error instanceof cloud_transport_js_1.CloudTransportError))
+                throw error;
+            throw new CapabilityError('Capability discovery HTTP exchange failed.', {
+                status: error.status, errorCode: `CAPABILITY_${error.kind}`,
+            });
+        }
+        const { value, status, ok } = response;
+        if (!ok) {
+            if (!record(value) || !text(value.errorCode) || typeof value.message !== 'string') {
+                throw new CapabilityError('Invalid capability error response.', { status, errorCode: 'CAPABILITY_PROTOCOL_ERROR' });
+            }
+            throw new CapabilityError(value.message, { status, errorCode: value.errorCode });
+        }
+        return discovery(value, status);
+    }
+}
+exports.CapabilitiesClient = CapabilitiesClient;
+/** Uses configureClient()/runtime environment, resolving the host and workspace key on every call. */
+exports.capabilities = new CapabilitiesClient();
+//# sourceMappingURL=capabilities.js.map

package/dist/cjs/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/capabilities.ts"],"names":[],"mappings":"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","sourcesContent":["import { CloudTransport, CloudTransportError, type CloudTransportConfig } from './cloud-transport.js';\r\nimport { getClient, type HttpClient } from './openapi/client.js';\r\n\r\nexport type CapabilityCode = 'namespace.v2' | 'source.v1' | 'stream.v2' | 'control.v1' | 'control.invoke.v1';\r\nexport type CapabilityState = 'disabled' | 'not_supported' | 'unavailable' | 'readiness_unknown' | 'ready';\r\nexport type CapabilityAvailability = 'unavailable' | 'unknown' | 'available';\r\n\r\nexport interface PublicCapability {\r\n  code: CapabilityCode;\r\n  /** Public release and workspace gates; does not establish runtime readiness. */\r\n  releaseEnabled: boolean;\r\n  /** Server-assessed implementation/readiness, never inferred from releaseEnabled. */\r\n  enabled: boolean;\r\n  /** Authorization summary, not a grant for every individual Control code. */\r\n  allowed: boolean;\r\n  state: CapabilityState;\r\n  /** Not device online status or execution/ACK confirmation. */\r\n  availability: CapabilityAvailability;\r\n  contractVersions: string[];\r\n}\r\n\r\nexport interface CapabilityDeprecation {\r\n  contract: string;\r\n  replacement?: string;\r\n  sunsetAt?: string;\r\n}\r\n\r\nexport interface CapabilityDiscoverResponse {\r\n  product: 'cloud';\r\n  /** Trusted server configuration only; absent when unconfigured. */\r\n  productVersion?: string;\r\n  contractVersion: '1.0';\r\n  apiContractVersions: string[];\r\n  interpreterContractVersions: string[];\r\n  /** Public SDK contract labels, not npm package versions. */\r\n  sdkContractVersions: string[];\r\n  capabilities: PublicCapability[];\r\n  deprecations: CapabilityDeprecation[];\r\n}\r\n\r\nexport interface CapabilityErrorInfo {\r\n  status?: number;\r\n  /** Gateway string code (including unknown future codes), or an SDK-local CAPABILITY_* code. */\r\n  errorCode: string;\r\n}\r\n\r\nexport class CapabilityError extends Error {\r\n  readonly status?: number;\r\n  readonly errorCode: string;\r\n  readonly retryable = false;\r\n\r\n  constructor(message: string, info: CapabilityErrorInfo) {\r\n    super(message);\r\n    this.name = 'CapabilityError';\r\n    this.status = info.status;\r\n    this.errorCode = info.errorCode;\r\n  }\r\n}\r\n\r\nconst contracts: Record<CapabilityCode, string[]> = {\r\n  'namespace.v2': ['openapi/v2'],\r\n  'source.v1': ['openapi/v1'],\r\n  'stream.v2': ['tier0-stream/v2'],\r\n  'control.v1': ['openapi/v1', 'control/v1'],\r\n  'control.invoke.v1': ['openapi/v1', 'tier0-stream/v2', 'control/v1'],\r\n};\r\n\r\nfunction record(value: unknown): value is Record<string, unknown> {\r\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\r\n}\r\nfunction text(value: unknown): value is string {\r\n  return typeof value === 'string' && value.length > 0;\r\n}\r\nfunction strings(value: unknown): value is string[] {\r\n  return Array.isArray(value) && value.every(text) && new Set(value).size === value.length;\r\n}\r\n\r\n/** Validate and explicitly project the frozen contract; unknown capabilities/extension fields are ignored. */\r\nfunction discovery(value: unknown, status: number): CapabilityDiscoverResponse {\r\n  const fail = (version = false): never => {\r\n    throw new CapabilityError(version ? 'Unsupported capability contract version.' : 'Invalid capability discovery response.', {\r\n      status, errorCode: version ? 'CAPABILITY_UNSUPPORTED_VERSION' : 'CAPABILITY_PROTOCOL_ERROR',\r\n    });\r\n  };\r\n  if (!record(value)) return fail();\r\n  if (!text(value.product) || !text(value.contractVersion) ||\r\n      !strings(value.apiContractVersions) || !strings(value.interpreterContractVersions) || !strings(value.sdkContractVersions) ||\r\n      !Array.isArray(value.capabilities) || !Array.isArray(value.deprecations) ||\r\n      (value.productVersion !== undefined && !text(value.productVersion))) return fail();\r\n  if (value.product !== 'cloud' || value.contractVersion !== '1.0' ||\r\n      !value.apiContractVersions.includes('openapi/v1') ||\r\n      !value.interpreterContractVersions.includes('tier0-stream/v2') ||\r\n      !value.sdkContractVersions.includes('control/v1')) return fail(true);\r\n\r\n  const capabilities: PublicCapability[] = [];\r\n  const seen = new Set<string>();\r\n  for (const item of value.capabilities) {\r\n    if (!record(item) || !text(item.code)) return fail();\r\n    if (!Object.prototype.hasOwnProperty.call(contracts, item.code)) continue;\r\n    const code = item.code as CapabilityCode;\r\n    if (seen.has(code)) return fail();\r\n    seen.add(code);\r\n    if (typeof item.releaseEnabled !== 'boolean' || typeof item.enabled !== 'boolean' || typeof item.allowed !== 'boolean' ||\r\n        !['disabled', 'not_supported', 'unavailable', 'readiness_unknown', 'ready'].includes(item.state as string) ||\r\n        !['unavailable', 'unknown', 'available'].includes(item.availability as string) || !strings(item.contractVersions)) return fail();\r\n    if (contracts[code].some(version =>\r\n      !(item.contractVersions as string[]).includes(version) ||\r\n      (version.startsWith('openapi/') && !(value.apiContractVersions as string[]).includes(version)))) return fail(true);\r\n    const ready = item.state === 'ready';\r\n    const expectedAvailability = ready ? 'available' : item.state === 'readiness_unknown' ? 'unknown' : 'unavailable';\r\n    if (item.enabled !== ready || item.availability !== expectedAvailability ||\r\n        (ready && (!item.releaseEnabled || !item.allowed)) ||\r\n        (item.state === 'disabled' ? item.releaseEnabled : !item.releaseEnabled)) return fail();\r\n    capabilities.push({\r\n      code, releaseEnabled: item.releaseEnabled, enabled: item.enabled, allowed: item.allowed,\r\n      state: item.state as CapabilityState, availability: item.availability as CapabilityAvailability,\r\n      contractVersions: [...item.contractVersions],\r\n    });\r\n  }\r\n  const deprecations: CapabilityDeprecation[] = [];\r\n  for (const item of value.deprecations) {\r\n    if (!record(item) || !text(item.contract) ||\r\n        (item.replacement !== undefined && !text(item.replacement)) ||\r\n        (item.sunsetAt !== undefined && !text(item.sunsetAt))) return fail();\r\n    deprecations.push({ contract: item.contract,\r\n      ...(item.replacement === undefined ? {} : { replacement: item.replacement as string }),\r\n      ...(item.sunsetAt === undefined ? {} : { sunsetAt: item.sunsetAt as string }),\r\n    });\r\n  }\r\n  return {\r\n    product: 'cloud', ...(value.productVersion === undefined ? {} : { productVersion: value.productVersion as string }),\r\n    contractVersion: '1.0', apiContractVersions: [...value.apiContractVersions],\r\n    interpreterContractVersions: [...value.interpreterContractVersions], sdkContractVersions: [...value.sdkContractVersions],\r\n    capabilities, deprecations,\r\n  };\r\n}\r\n\r\nexport class CapabilitiesClient {\r\n  private readonly transport: CloudTransport;\r\n\r\n  constructor(resolveClient: () => HttpClient = getClient, config: CloudTransportConfig = {}) {\r\n    this.transport = new CloudTransport(resolveClient, config);\r\n  }\r\n\r\n  /** Workspace comes exclusively from the authenticated key. One POST, no automatic retries or caching. */\r\n  async discover(): Promise<CapabilityDiscoverResponse> {\r\n    if (arguments.length !== 0) throw new TypeError('Tier0 SDK: capability discovery accepts no arguments.');\r\n    let response: Awaited<ReturnType<CloudTransport['post']>>;\r\n    try {\r\n      response = await this.transport.post('/openapi/v1/capabilities/discover', {});\r\n    } catch (error) {\r\n      if (!(error instanceof CloudTransportError)) throw error;\r\n      throw new CapabilityError('Capability discovery HTTP exchange failed.', {\r\n        status: error.status, errorCode: `CAPABILITY_${error.kind}`,\r\n      });\r\n    }\r\n    const { value, status, ok } = response;\r\n    if (!ok) {\r\n      if (!record(value) || !text(value.errorCode) || typeof value.message !== 'string') {\r\n        throw new CapabilityError('Invalid capability error response.', { status, errorCode: 'CAPABILITY_PROTOCOL_ERROR' });\r\n      }\r\n      throw new CapabilityError(value.message, { status, errorCode: value.errorCode });\r\n    }\r\n    return discovery(value, status);\r\n  }\r\n}\r\n\r\n/** Uses configureClient()/runtime environment, resolving the host and workspace key on every call. */\r\nexport const capabilities = new CapabilitiesClient();\r\n"]}