@tier0/sdk-v2 0.6.3 → 0.7.2

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;

package/dist/esm/controls.js

@@ -1,166 +0,0 @@
-import { getClient } from './openapi/client.js';
-import { DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS } from './cloud-transport.js';
-import { UnsV2ClientCore, UnsV2Error } from './uns-v2/client.js';
-import { UnsV2RawNumber } from './uns-v2/codec.js';
-export const DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS;
-/** No Control error is automatically retried, including authentication failures. */
-export 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;
-    }
-}
-/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */
-export 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';
-    }
-}
-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 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,
-    };
-}
-export class ControlsClient {
-    uns;
-    constructor(resolveClient = getClient, config = {}) {
-        this.uns = new 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 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 };
-            },
-        };
-    }
-}
-/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */
-export const controls = new ControlsClient();
-//# sourceMappingURL=controls.js.map

package/dist/esm/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/skills/tier0-sdk-v2/tier0-sdk-v2-controls/SKILL.md

@@ -1,65 +0,0 @@
----
-name: tier0-sdk-v2-controls
-description: 使用 @tier0/sdk-v2 发现、描述和调用 Tier0 Control 业务契约，区分读写副作用、契约版本、幂等要求和执行结果未知。
----
-
-# Control 契约调用
-
-Control 是已发布的业务调用入口；它可由 Stream 提供，但调用方不选择内部 streamId、entryId 或部署版本。使用服务端 client.controls，实际调用 `/openapi/v2/uns/controls/discover|describe|invoke`。
-
-调用按服务端现有统一权限及 App 业务策略校验；不配置逐 Key 的 Control scopes/codes。
-
-## 发现和读取契约
-
-```ts
-import { createClient } from '@tier0/sdk-v2';
-
-export async function discoverControls(search: string) {
-  return createClient().controls.discover({ search, page: 1, size: 20 });
-}
-export async function describeControl(code: string) {
-  return createClient().controls.use({ code }).describe();
-}
-```
-
-discover 返回 total/list，分页从 1 开始，size 为 1–200。code 取自发现结果，不由显示名称猜测。describe 返回 inputSchema、outputSchema、sideEffect、idempotency、contractVersion、timeoutMs 和 status。
-
-## 构造调用
-
-1. 依据 inputSchema 填写输入，业务 JSON 不等于任意控制参数。SDK 的泛型只提供静态提示，不能替代契约校验。
-2. 判断 sideEffect=read/write，与用户本次任务的授权范围一致。
-3. 当 idempotency=required 时提供稳定的业务意图键；optional/none 按契约决定，不自动生成 UUID 重试。
-4. 调用后检查业务 result 与 status，记录 runID/contractVersion，不能只看请求未抛错。
-
-```ts
-import {
-  createClient, ControlResultUnknownError, type ControlJSON,
-} from '@tier0/sdk-v2';
-
-export async function invokePreparedControl(code: string, input: ControlJSON, intentKey?: string) {
-  const handle = createClient().controls.use({ code });
-  const definition = await handle.describe();
-  if (definition.idempotency === 'required' && !intentKey) {
-    throw new Error('该 Control 要求业务幂等键');
-  }
-  // 调用方已经按 definition.inputSchema 校验输入，并确认本次业务意图。
-  try {
-    return await handle.invoke(input, intentKey ? { idempotencyKey: intentKey } : {});
-  } catch (error) {
-    if (error instanceof ControlResultUnknownError) {
-      return { outcomeUnknown: true as const, runID: error.runID, errorCode: error.errorCode };
-    }
-    throw error;
-  }
-}
-```
-
-幂等键非空、不能有首尾空白，最多 128 UTF-8 字节。输入使用 JSON；需要保留精确数字时可用 UnsV2RawNumber，不传 Date、函数、循环对象、bigint、NaN/Infinity。业务 input 内名为 timeoutMs/streamId 的字段仍只是业务输入；不能借它覆盖服务端绑定、版本或执行超时。
-
-## 返回与失败
-
-成功值为直接对象：code（Control 标识）、contractVersion、result、runID、status、replayed。这里的 code 不是 HTTP 业务状态码；replayed 只有服务端明确报告重放时才为 true。
-
-`ControlError` 含 status/errorCode/runID 与 requestId/execution/retry 等信息，SDK 不自动重试。`ControlResultUnknownError` 表示执行可能已经发生，包括调用响应无法证明最终结果的情况；按业务或平台运行记录对账。本 SDK 未提供通用 `controls.getRun`，不要虚构方法。若业务明确允许重放，保留原 key 和原输入，不能换新 key 重做。
-
-`client.capabilities.discover()` 的 control.invoke.v1 就绪只是入口条件，不等于有权调用每一个 Control。执行源发布和内部绑定管理请使用 [Stream Skill](../tier0-sdk-v2-stream/SKILL.md)。