@tier0/sdk-v2 0.6.2 → 0.7.2

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

@@ -14,12 +14,12 @@
 | --- | --- |
 | revision | 草稿修订；传给下次写入的 expectedRevision，冲突时显式处理 |
 | activeVersion | 不可变发布版本 ID；回滚的 versionId 使用这个 ID，不使用发布序号 |
-| activeRelease | 本次事务记录的正整数发布序号；与 runs.list 中的 release 对照；无活跃发布或旧回执未记录时省略 |
+| activeRelease | 本次事务记录的正整数发布序号；与 runs.list 中的 release 对照；无活跃发布或回执未记录时省略 |
 
-programs 回执的 activeVersion:'0' 表示无活跃版本；新增 activeRelease 不用 0 表示未发布。原生 documents 回执的既有 activeRelease 约定不变。
+programs 回执的 activeVersion:'0' 表示无活跃版本；programs 的 activeRelease 此时省略；documents 的 activeRelease 此时为 0。
 
 ```ts
-import { createClient, type Tier0Client, type CloudStreamDocumentView } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type CloudStreamDocumentView, type CloudStreamStopView } from '@tier0/sdk-v2';
 
 export async function deployStream(current: CloudStreamDocumentView, intentKey: string, client: Tier0Client = createClient()) {
   const sources = current.document.sources ?? [];
@@ -35,40 +35,42 @@ export async function deployStream(current: CloudStreamDocumentView, intentKey:
   }
   const release = receipt.data.activeRelease;
   if (release === undefined || BigInt(String(release)) <= 0n) {
-    throw new Error('历史回执缺少发布编号；保留原请求，不用当前发布编号替代');
+    throw new Error('回执缺少发布编号；保留原请求，不用当前发布编号替代');
   }
   return { receipt, release };
 }
 
-export async function disableStream(id: string, intentKey: string, client: Tier0Client = createClient()) {
-  const { data: current } = await client.stream.documents.get({ id });
-  if (String(current.activeRelease) === '0') throw new Error('没有活跃发布可停用');
+export async function disableStream(
+  current: Pick<CloudStreamStopView, 'id' | 'revision' | 'activeRelease'>,
+  intentKey: string, client: Tier0Client = createClient(),
+) {
+  if (BigInt(String(current.activeRelease)) <= 0n) throw new Error('没有活跃发布可停用');
   const receipt = await client.stream.documents.disable({
-    id, expectedRevision: current.revision, expectedActiveRelease: current.activeRelease,
+    id: current.id, expectedRevision: current.revision, expectedActiveRelease: current.activeRelease,
     dryRun: false, idempotencyKey: intentKey,
   });
-  const after = await client.stream.documents.get({ id });
-  if (String(after.data.activeRelease) !== '0') throw new Error('停用读回未确认');
-  return { receipt, current: after.data };
+  if (!('id' in receipt.data) || String(receipt.data.activeRelease) !== '0') {
+    throw new Error('未返回停用回执');
+  }
+  return { receipt, current: receipt.data };
 }
 ```
 
-将创建或更新回执的 current 传给 deployStream，只发一次发布请求。只有手上没有草稿快照时才先 documents.get。使用 [按发布号查询运行记录](read.md#观察本次发布) 才能观察这次发布，观察窗口汇总不能证明该版本运行。发布成功不表示外部连接健康或执行成功。停用保留草稿。仅修改草稿的任务不额外发布/停用。
+将创建或更新回执的 current 传给 deployStream，只发一次发布请求。只有手上没有草稿快照时才先 documents.get。使用 [按发布号查询运行记录](read.md#观察本次发布) 才能观察这次发布，观察窗口汇总不能证明该版本运行。发布成功不表示外部连接健康或执行成功。停用使用已确认的 id/revision/activeRelease（可来自发布回执），返回的 current 可直接用于删除；不需要前后各 get。停用保留草稿。仅修改草稿的任务不额外发布/停用。
 
 ## 回滚到明确版本
 
 ```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type CloudStreamStopView } from '@tier0/sdk-v2';
 
 export async function rollbackStream(
-  id: string, versionId: string, intentKey: string, client: Tier0Client = createClient(),
+  current: Pick<CloudStreamStopView, 'id' | 'revision'>, versionId: string, intentKey: string, client: Tier0Client = createClient(),
 ) {
-  // versionId 必须先从 programs.versions.list({id,page,size}) 查询并选定。
-  const { data: current } = await client.stream.documents.get({ id });
+  // versionId 使用已知发布回执的 activeVersion，或从 programs.versions.list 选定。
   return client.stream.programs.rollback({
-    id, versionId, expectedRevision: current.revision, dryRun: false, idempotencyKey: intentKey,
+    id: current.id, versionId, expectedRevision: current.revision, dryRun: false, idempotencyKey: intentKey,
   });
 }
 ```
 
-检查回执 activeVersion 与 activeRelease。超时或 UnsV2OutcomeUnknownError 时保留原路由、载荷和幂等键；允许恢复时原样重发以取得原回执，不用新键再次发布。旧回执可能没有 activeRelease，不能读取当前 head 后冒充旧请求的发布编号。相同草稿使用不同键仍会创建新发布，expectedRevision 仅保护草稿修订。预览用 dryRun=true，返回 validated/sideEffects，不保证稍后的实际发布一定成功。
+检查回执 activeVersion 与 activeRelease。超时或 UnsV2OutcomeUnknownError 时保留原路由、载荷和幂等键；允许恢复时原样重发以取得原回执，不用新键再次发布。回执缺少 activeRelease 时不能用当前 head 替代本次请求的发布编号。相同草稿使用不同键仍会创建新发布，expectedRevision 仅保护草稿修订。预览用 dryRun=true，返回 validated/sideEffects，不保证稍后的实际发布一定成功。

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

@@ -6,7 +6,7 @@
 
 ## 保存原生程序草稿
 
-使用完整原生 `document`：script 是 `{code,timeoutMs}`，sources 使用 alias。这与 `program` 的 script 字符串形态不同；不能把旧 Flow 脚本直接改名为新字段。
+使用完整原生 `document`：script 是 `{code,timeoutMs}`，sources 使用 alias。这与 `program` 的 script 字符串形态不同。
 
 ```ts
 import { createClient, type Tier0Client, type CloudStreamDocument } from '@tier0/sdk-v2';
@@ -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-stream/references/update.md

@@ -6,23 +6,21 @@
 | --- | --- | --- | --- |
 | id | string | 是 | 十进制字符串 |
 | document | CloudStreamDocument | 是 | name、model、script、sources、entries 完整文档 |
-| expectedRevision | integer | 建议始终提供 | get 返回修订，防止覆盖他人修改 |
+| expectedRevision | integer | 建议始终提供 | 当前回执或查询的修订，防止覆盖他人修改 |
 | dryRun | boolean | 是 | true 预检；false 保存 |
 | idempotencyKey | string | 否 | 本次更新独立意图键 |
 
 ## 示例：更新描述，保持脚本和绑定
 
 ```ts
-import { createClient, type Tier0Client, type CloudStreamDocument } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type CloudStreamDocument, type CloudStreamDocumentView } from '@tier0/sdk-v2';
 
 export async function updateStreamDescription(
-  id: string, description: string, intentKey: string, client: Tier0Client = createClient(),
+  current: CloudStreamDocumentView, description: string, intentKey: string, client: Tier0Client = createClient(),
 ) {
-  const { data: current } = await client.stream.documents.get({ id, view: 'full' });
-  if (!('document' in current)) throw new Error('需要完整 Stream 文档');
   const document: CloudStreamDocument = { ...current.document, description };
   const saved = await client.stream.documents.update({
-    id, expectedRevision: current.revision, document, dryRun: false, idempotencyKey: intentKey,
+    id: current.id, expectedRevision: current.revision, document, dryRun: false, idempotencyKey: intentKey,
   });
   if (!('id' in saved.data)) throw new Error('未返回已保存文档');
   return { receipt: saved, current: saved.data };
@@ -31,4 +29,4 @@ export async function updateStreamDescription(
 
 代码应用可直接用 documents.update({id, expectedRevision, program, dryRun:false, idempotencyKey})，由服务端编译入口和绑定。编辑完整文档时保留 script.code/timeoutMs，并同步 entries/sources；写入本身执行校验，只有需要提前展示问题时才单独 validate。不要对documents.get 的 summary 做展开更新。
 
-响应是完整 CloudStreamDocumentView 或预检结果；把 saved.data 直接传给下一步[发布示例](deploy.md)，无需为了 revision 再读取。已有当前完整文档时可省去示例最初的 get。保存草稿不会自动部署，activeDocument 可能仍是旧发布版本。VERSION_CONFLICT 后重新读取、比较并决策；不无条件覆盖。
+响应是完整 CloudStreamDocumentView 或预检结果；把 saved.data 直接传给下一步[发布示例](deploy.md)，无需为了 revision 再读取。示例复用创建/更新回执；只有缺少完整文档时才先 get({id,view:"full"}) 并确认 document 存在。保存草稿不会自动部署，activeDocument 可能仍是旧发布版本。VERSION_CONFLICT 后重新读取、比较并决策；不无条件覆盖。

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

@@ -10,8 +10,6 @@ description: 使用 @tier0/sdk-v2 查询 Tier0 凭证身份、平台版本、MQT
 | 诊断 Key 所属 Workspace 和权限 | [whoami](references/whoami.md) |
 | 查看平台版本、解析 Broker 地址 | [info](references/info.md) |
 
-v1 的内部 reload 接口不属于 v2 公共 SDK，不能在普通诊断时调用。
-
 使用服务端 `createClient()` 或显式传入 apiHost/apiKey。系统排查从只读信息开始，不因功能不可用自动创建 Key、修改权限或部署服务。
 
 ## 最小诊断
@@ -45,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 | 实际调用仍要检查具体资源的权限、配置和依赖 |
+
+本数据 SDK 的能力目录识别 namespace.v2、source、stream；其他 SDK 的可选交互能力按各自合同处理，不阻断 Namespace 发现。Source/Stream 的 contractVersions 使用 openapi/v2，不要求或返回解释器版本。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。顶层要求受支持的核心 OpenAPI v2 合同，已识别能力也必须满足其合同；不要求全局交互 SDK 标签，不把未知能力投影为已支持。
 
-能力目录当前识别 namespace.v2、source、stream、control.v1、control.invoke.v1。Source/Stream 的 contractVersions 使用 openapi/v2，不要求或返回解释器版本。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。
+发现统一使用 `POST /openapi/v2/capabilities/discover`，请求为 `{}`，不接受 Workspace 参数。Cloud / Enterprise 返回同一合同；此 SDK 只消费 Namespace、Source、Stream 管理能力；App 交互域由 App SDK 提供，其版本不作为管理接口的前置条件。SDK 只投影已知操作与公开诊断字段；未知扩展不被解释为就绪，不自动重试。
 
 ## 定位问题
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-system/references/info.md

@@ -19,5 +19,3 @@ export async function inspectService(client: Tier0Client = createClient()) {
 返回已解包对象，name/version/capabilities/mqttBroker 均可能省略。mqttBroker 是连接串，可能裸 host、host:port、tcp://host:1883 或完整 ws/wss，不能直接拼 wss:// 前缀。toWebSocketUrl 保留已有 WebSocket URL；TCP 端口不直接复用为 WebSocket 端口。实际端口/路径由环境决定。
 
 info.capabilities 的简略字符串列表不是就绪证明。进一步读取 client.capabilities.discover 的 releaseEnabled、allowed、state、availability，区分开关、授权与运行能力；详见[系统 Skill](../SKILL.md)。
-
-v1 的 /gw/reload 是内部管理操作，未纳入 v2 公共 SDK，不复制旧 reload 示例，也不在连通性诊断中尝试重载服务。

package/skills/tier0-sdk-v2/tier0-sdk-v2-system/references/whoami.md

@@ -14,7 +14,7 @@ export async function inspectCredential(client: Tier0Client = createClient()) {
 }
 ```
 
-返回已解包的 userID/userName/email/workspaceID/workspaceName/apiKeyName/keyPrefix/permissions/roles/keyType。v2 对大整数保留 number|bigint，不能套用 v1 “一定已经丢精度”的描述；需要字符串时用 String，不先转 Number。
+返回已解包的 userID/userName/email/workspaceID/workspaceName/apiKeyName/keyPrefix/permissions/roles/keyType。大整数保留 number|bigint；需要字符串时用 String，不先转 Number。
 
 App Key 是共享业务凭证，不代表访问 App 的自然人。whoami 不能用于登录、当前用户、操作人审计或选择通知收件人；当前人来自应用认证会话，收件人从成员数据解析。
 

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"]}

package/dist/esm/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;