@tier0/sdk-v2 0.9.1 → 0.9.3

package/README.md

@@ -2,7 +2,9 @@
 
 Tier0 云端统一 TypeScript / JavaScript SDK，数据管理与 App Stream 交互均使用 `@tier0/sdk-v2`。旧 SDK 不再作为依赖。
 
-`0.9.1` 包含接口合同变更，升级时需核对下方使用方式并确认目标后端已部署对应合同。平台接口统一使用 OpenAPI v2，能力发现使用 `state + reasonCode + operations`。Stream 请求与消息交互统一到本包的 `client.streams`；`client.stream` 保留 Stream 管理。文件上传支持并发分片与断点续传。
+`0.9.3` 同步集合授权合同：授予既有集合访问权限时无需提供别名，并更新生成类型与使用说明。集合声明的 `name` / `alias` 要求保持不变。
+
+`0.9.2` 包含接口合同变更，升级时需核对下方使用方式并确认目标后端已部署对应合同。平台接口统一使用 OpenAPI v2，能力发现使用 `state + reasonCode + operations`。Stream 请求与消息交互统一到本包的 `client.streams`；`client.stream` 保留 Stream 管理。文件上传支持并发分片与断点续传。
 
 Collection 声明必须同时提供业务名称 `name`（例如「生产工单」）和稳定程序标识 `alias`（例如 `production_orders`），高层声明与底层请求类型一致。`name` 是唯一展示名称，不支持 `displayName`；ensure 仅在创建时写入名称，重复 ensure 保留用户改名，同目录重名明确报错。使用前需确认后端已包含 `business-name/1` 契约。
 
@@ -18,13 +20,13 @@ Collection 声明必须同时提供业务名称 `name`（例如「生产工单
 
 ## 安装与初始化
 
-维护者发布前在本仓库运行 `npm ci`、`npm run check`，并验证生成的 `.tgz`。本分支的功能应使用检查通过的 `tier0-sdk-v2-0.9.1.tgz` 在业务项目中验证：
+维护者发布前在本仓库运行 `npm ci`、`npm run check`，并验证生成的 `.tgz`。本分支的功能应使用检查通过的 `tier0-sdk-v2-0.9.3.tgz` 在业务项目中验证：
 
 ```sh
-npm install /path/to/tier0-sdk-v2-0.9.1.tgz
+npm install /path/to/tier0-sdk-v2-0.9.3.tgz
 ```
 
-`0.9.1` 正式发布后再使用 `npm install @tier0/sdk-v2@0.9.1`。发布前，npm 的既有版本和 `next` 标签不代表本分支的完整功能。
+`0.9.3` 正式发布后再使用 `npm install @tier0/sdk-v2@0.9.3`。发布前，npm 的既有版本和 `next` 标签不代表本分支的完整功能。
 
 ```ts
 import { createClient } from '@tier0/sdk-v2';
@@ -97,7 +99,7 @@ HTTP Source 统一使用 `protocol: 'http-api'`，显式设置 `config.role: 'cl
 Source/Stream 仍保留 `{ code, msg, requestId, data }` 响应以及 `UnsV2Error` 错误类型。Source 配置统一使用 `source.documents`；Stream 草稿统一通过 `stream.documents` 创建、读取、校验和修改，输入 `program` 与 `document` 二选一。发布和回滚仍走 `stream.programs`。保存、部署、运行成功分别判断。
 
 - 已知 Source ID/revision 且没有 Stream 引用时，可 [直接 patch 或变更状态](skills/tier0-sdk-v2/tier0-sdk-v2-source/references/update.md)；有引用时仍按精确意图确认影响。
-- Stream 创建/更新回执的 revision 可直接用于发布；[发布回执](skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/deploy.md) 的 activeRelease 用于观察这次发布，无需前后各查询一次。
+- Stream 发布和回滚可携带并发守卫：有生效发布时使用 `expectedActiveRelease`，无生效发布时使用 `expectedReleaseState: 'inactive'`。[发布回执](skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/deploy.md) 的 activeRelease 也可用于观察这次发布。
 - 单条 Record 新增可用 [returnDocument:'after'](skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/create.md) 同次取得创建快照；[App 数据层](skills/tier0-sdk-v2/tier0-sdk-v2-data/references/read-write.md) 支持相同选择及投影类型。
 
 从最初提交迁移：`uns.sourceList` → `source.documents.list`；`uns.sourceDocumentGet` → `source.documents.get`；`uns.streamProgramDeploy` → `stream.programs.deploy`；`uns.streamDocumentValidate` → `stream.documents.validate`。这些管理方法已移出主入口的 `uns`。底层 `createUnsV2Client()` 仍提供完整生成契约供契约工具使用；数据专用客户端可用 `createUnsDataClient()`。
@@ -106,6 +108,8 @@ Source/Stream 仍保留 `{ code, msg, requestId, data }` 响应以及 `UnsV2Erro
 
 ## UNS 数据访问
 
+创建本 App 集合使用 `defineCollection` / `appCollectionsEnsure`，`ownerAppId` 表示唯一所属 App。使用已有或其他 App 共享的集合，直接向 `tier0.uns.recordFind`、`recordInsertOne` 等现有接口传入实际 `collectionId`；无需新增声明或配置服务端 alias，也不改变集合归属。App Key 仍须已有覆盖该集合及操作的授权，知道 ID 不代表获得权限。
+
 新建 Schema 的数值字段使用明确格式：整数为 `type: 'integer', format: 'int32'`，小数为 `type: 'number', format: 'double'`，明确需要单精度时指定 `format: 'float'`。App 数据层编译 Zod 声明时，会递归为未指定格式的 integer/number 补齐 int32/double，并保留显式格式；直接调用 UNS/MCP 时由调用方提供 format。这些是类型注解，不新增数值范围或舍入规则；ensure 不改写已有字段注解，已有 legacy 字段需通过 schema:replace 单独迁移。
 
 ```ts

package/dist/cjs/uns-v2/generated.d.ts

@@ -516,6 +516,8 @@ export type UnsV2StreamProgramDeployReq = {
     "id": string;
     "expectedRevision"?: UnsV2Integer;
     "expectedSourceRevision"?: UnsV2Integer;
+    "expectedActiveRelease"?: UnsV2Integer;
+    "expectedReleaseState"?: "inactive";
 };
 export type UnsV2StreamProgramDeployResponse = {
     "code": UnsV2Integer;
@@ -530,6 +532,8 @@ export type UnsV2StreamProgramRollbackReq = {
     "expectedRevision"?: UnsV2Integer;
     "expectedSourceRevision"?: UnsV2Integer;
     "versionId": string;
+    "expectedActiveRelease"?: UnsV2Integer;
+    "expectedReleaseState"?: "inactive";
 };
 export type UnsV2StreamProgramRollbackResponse = {
     "code": UnsV2Integer;
@@ -1892,7 +1896,7 @@ export type CloudStreamSampleTestResponse = {
     });
 };
 export type CloudAppDataGrant = {
-    "alias": string;
+    "alias"?: string;
     "collectionId": string;
     "permissions": Array<"record:read" | "record:write" | "record:delete" | "sample:read" | "sample:write">;
     "dataRule"?: CloudAppDataRule;
@@ -5236,6 +5240,9 @@ export declare const UNS_V2_CODEC_SCHEMAS: {
             readonly expectedSourceRevision: {
                 readonly k: "j";
             };
+            readonly expectedActiveRelease: {
+                readonly k: "j";
+            };
         };
     };
     readonly UnsV2StreamProgramDeployResponse: {
@@ -5263,6 +5270,9 @@ export declare const UNS_V2_CODEC_SCHEMAS: {
             readonly expectedSourceRevision: {
                 readonly k: "j";
             };
+            readonly expectedActiveRelease: {
+                readonly k: "j";
+            };
         };
     };
     readonly UnsV2StreamProgramRollbackResponse: {
@@ -9814,11 +9824,11 @@ export declare const UNS_V2_CODEC_SCHEMAS: {
 };
 export declare const UNS_V2_CONTRACT_PROVENANCE: {
     readonly repository: "FREEZONEX/Tier0-Backend";
-    readonly revision: "5ba6c3af432d5200674f7cb1a3edd31b255ef64b";
+    readonly revision: "0d8cb6dd7c72fb794dd1d63f5c7efb5017804545";
     readonly version: "5.0.0";
     readonly source: "service/unssvr/internal/domain/unsv2/contract_generated.go#ContractJSON";
-    readonly cloudRevision: "5ba6c3af432d5200674f7cb1a3edd31b255ef64b";
-    readonly cloudContractRevision: "cloud-source-impact/2+source-vendor/2+app-create-capability/1+data/3+record-reads/1+stream-receipt/1+stream-run-error/1+collection-namespace/1+business-name/1+http-acquisition/2+http-source-role/1+http-source-request/1+sql-inline-credentials/1+app-collection/2+collection-ownership/1+metadata/1+app-context/3+collection-ttl/1+error-model/1+crud-consolidation/1+record-insert-return/1+lifecycle-consolidation/1+mutation-defaults/1+api-surface/2+source-stream-single-model+app-data/2+hosted-control/1+source-bindings/1+record-notifications/1+record-delete-samples/1+stream-history/1+app-collections/1+http-in/1+app-resource-access/2+stream-control-probe-retirement/1+http-push-retirement/1";
+    readonly cloudRevision: "0d8cb6dd7c72fb794dd1d63f5c7efb5017804545";
+    readonly cloudContractRevision: "cloud-source-impact/2+source-vendor/2+app-create-capability/1+data/3+record-reads/1+stream-receipt/1+stream-run-error/1+stream-deploy-guard/1+collection-namespace/1+business-name/1+http-acquisition/2+http-source-role/1+http-source-request/1+sql-inline-credentials/1+app-collection/2+collection-ownership/1+metadata/1+app-context/3+collection-ttl/1+error-model/1+crud-consolidation/1+record-insert-return/1+lifecycle-consolidation/1+mutation-defaults/1+api-surface/2+source-stream-single-model+app-data/3+hosted-control/1+source-bindings/1+record-notifications/1+record-delete-samples/1+stream-history/1+app-collections/1+http-in/1+app-resource-access/2+stream-control-probe-retirement/1+http-push-retirement/1";
     readonly resolvedCloudContract: true;
     readonly enterpriseBase: {
         readonly repository: "FREEZONEX/Tier0-Enterprise-New";
@@ -9834,37 +9844,37 @@ export declare const UNS_V2_CONTRACT_PROVENANCE: {
             readonly capability: "x-tier0-opcua-server: static available=false; online availability is workspace/registry authoritative";
         };
     };
-    readonly sourceDerivedContractSHA256: "a8c280d90b9d865a80637d7b563bd72611aead54bf0422a0cf83e05feaacd724";
+    readonly sourceDerivedContractSHA256: "8ebf585ff96fdffae9fa1e9ddd77a7b2e73431ebba0052fdaedf4ede6efddfe5";
     readonly schemaUpdates: readonly [{
         readonly scope: "source-stream-acquisition";
         readonly repository: "FREEZONEX/Tier0-Backend";
-        readonly revision: "5ba6c3af432d5200674f7cb1a3edd31b255ef64b";
+        readonly revision: "0d8cb6dd7c72fb794dd1d63f5c7efb5017804545";
         readonly sourceKind: "committed";
         readonly source: "share/unscontract/manifest.json";
-        readonly sourceSHA256: "c92e134799190fda29360a2983692ed47fb421a85fa7d92267ce091ac263dac8";
-        readonly sourceContractRevision: "cloud-source-impact/2+source-vendor/2+app-create-capability/1+data/3+record-reads/1+stream-receipt/1+stream-run-error/1+collection-namespace/1+business-name/1+http-acquisition/2+http-source-role/1+http-source-request/1+sql-inline-credentials/1+app-collection/2+collection-ownership/1+metadata/1+app-context/3+collection-ttl/1+error-model/1+crud-consolidation/1+record-insert-return/1+lifecycle-consolidation/1+mutation-defaults/1+api-surface/2+source-stream-single-model+app-data/2+hosted-control/1+source-bindings/1+record-notifications/1+record-delete-samples/1+stream-history/1+app-collections/1+http-in/1+app-resource-access/2+stream-control-probe-retirement/1+http-push-retirement/1";
+        readonly sourceSHA256: "a96cac51c46f1cfdd6a60a54c694999b9e5cc9f9ffb498fc912af6426c51d110";
+        readonly sourceContractRevision: "cloud-source-impact/2+source-vendor/2+app-create-capability/1+data/3+record-reads/1+stream-receipt/1+stream-run-error/1+stream-deploy-guard/1+collection-namespace/1+business-name/1+http-acquisition/2+http-source-role/1+http-source-request/1+sql-inline-credentials/1+app-collection/2+collection-ownership/1+metadata/1+app-context/3+collection-ttl/1+error-model/1+crud-consolidation/1+record-insert-return/1+lifecycle-consolidation/1+mutation-defaults/1+api-surface/2+source-stream-single-model+app-data/3+hosted-control/1+source-bindings/1+record-notifications/1+record-delete-samples/1+stream-history/1+app-collections/1+http-in/1+app-resource-access/2+stream-control-probe-retirement/1+http-push-retirement/1";
         readonly schemas: readonly ["CloudSourceCreateCredentials", "CloudSourceDocumentCreateReq", "CloudSourceDocumentUpdateReq", "UnsV2SourceStateUpdateReq", "CloudStreamDocumentCreateReq", "CloudStreamDocumentUpdateReq", "UnsV2StreamProgramDeployReq"];
         readonly inputs: {
             readonly "contracts/uns-v2/manifest.json": {
                 readonly path: "share/unscontract/manifest.json";
-                readonly sourceSHA256: "c92e134799190fda29360a2983692ed47fb421a85fa7d92267ce091ac263dac8";
-                readonly baseSHA256: "c92e134799190fda29360a2983692ed47fb421a85fa7d92267ce091ac263dac8";
-                readonly resultSHA256: "c92e134799190fda29360a2983692ed47fb421a85fa7d92267ce091ac263dac8";
+                readonly sourceSHA256: "a96cac51c46f1cfdd6a60a54c694999b9e5cc9f9ffb498fc912af6426c51d110";
+                readonly baseSHA256: "a96cac51c46f1cfdd6a60a54c694999b9e5cc9f9ffb498fc912af6426c51d110";
+                readonly resultSHA256: "a96cac51c46f1cfdd6a60a54c694999b9e5cc9f9ffb498fc912af6426c51d110";
             };
             readonly "contracts/uns-v2/contract.json": {
                 readonly path: "share/unscontract/manifest.json";
-                readonly sourceSHA256: "c92e134799190fda29360a2983692ed47fb421a85fa7d92267ce091ac263dac8";
-                readonly baseSHA256: "a8c280d90b9d865a80637d7b563bd72611aead54bf0422a0cf83e05feaacd724";
-                readonly resultSHA256: "a8c280d90b9d865a80637d7b563bd72611aead54bf0422a0cf83e05feaacd724";
+                readonly sourceSHA256: "a96cac51c46f1cfdd6a60a54c694999b9e5cc9f9ffb498fc912af6426c51d110";
+                readonly baseSHA256: "8ebf585ff96fdffae9fa1e9ddd77a7b2e73431ebba0052fdaedf4ede6efddfe5";
+                readonly resultSHA256: "8ebf585ff96fdffae9fa1e9ddd77a7b2e73431ebba0052fdaedf4ede6efddfe5";
             };
         };
     }];
     readonly note: "Pinned base with reviewed acquisition schema updates; schemaUpdates records the exact source revision and hashes. Other data-model inputs remain pinned.";
     readonly hashes: {
-        readonly contract: "a8c280d90b9d865a80637d7b563bd72611aead54bf0422a0cf83e05feaacd724";
+        readonly contract: "8ebf585ff96fdffae9fa1e9ddd77a7b2e73431ebba0052fdaedf4ede6efddfe5";
         readonly cloudSupport: "4ff9d5ff69e35e38459287cf15df45ab627684e2e2294dfd1e076ebc4fc34b46";
-        readonly manifest: "c92e134799190fda29360a2983692ed47fb421a85fa7d92267ce091ac263dac8";
-        readonly provenance: "5b80e631aaba726b90ef69845d95e798ff35163c3cf98352e23ee71e4e90bde0";
+        readonly manifest: "a96cac51c46f1cfdd6a60a54c694999b9e5cc9f9ffb498fc912af6426c51d110";
+        readonly provenance: "7c994e15d8910be30794d99d5e2b10ff2535fda6d7495717c499119890fd1fc4";
         readonly registry: "c74313c217742d50391a94c09e60d5c5bd1a89c305fa4145cbf23b35ba7dbcdb";
     };
     readonly publicOperationCount: 82;