@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/data-workflows.md

@@ -0,0 +1,69 @@
+# UNS 分页、采样与写入恢复
+
+## 完整游标遍历
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function* scanRecords(collectionId: string, signal?: AbortSignal) {
+  const client = createClient();
+  let cursor: string | undefined;
+  const seen = new Set<string>();
+  while (true) {
+    const { data } = await client.uns.recordFind({ collectionId, limit: 200, cursor }, { signal });
+    yield data.items;
+    if (!data.pageInfo.hasMore) return;
+    const next = data.pageInfo.nextCursor;
+    if (!next || seen.has(next)) throw new Error('服务端未返回可继续的游标');
+    seen.add(next);
+    cursor = next;
+  }
+}
+```
+
+消费方逐批处理以避免无限堆积内存；需要截止时用 AbortSignal。分页保证按返回游标继续，不保证跨请求保留相同行版本；导出审计要求一致快照时必须另行确认后端能力。
+
+## 历史采样
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function readHistory(collectionId: string, recordId: string, from: number, to: number) {
+  if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to <= from) {
+    throw new Error('时间应为有效的 Unix 毫秒范围');
+  }
+  return createClient().uns.sampleFind({
+    collectionId, recordIds: [recordId], from, to, limit: 200,
+  });
+}
+```
+
+返回可能分页；page 模式与 limit/cursor 互斥。Record 是业务实体，Sample 是该实体的时间序列，不用覆盖 Record 伪装保存历史。sampleDeleteRange 删除明确的时间范围，与删除 Record 的操作不可混淆。
+
+## 写入、事务与恢复
+
+```ts
+import { createClient, UnsV2Error, UnsV2OutcomeUnknownError, type UnsV2JSONValue } from '@tier0/sdk-v2';
+
+export async function insertRecord(collectionId: string, id: string, data: Record<string, UnsV2JSONValue>, intentKey: string) {
+  try {
+    return await createClient().uns.recordInsertOne({
+      collectionId, id, data, dryRun: false, idempotencyKey: intentKey,
+    });
+  } catch (error) {
+    if (error instanceof UnsV2OutcomeUnknownError) {
+      return { state: 'unknown' as const, requestId: error.requestId, replaySafe: error.retry.safe };
+    }
+    if (error instanceof UnsV2Error) {
+      return { state: 'rejected' as const, code: error.code, execution: error.execution, retry: error.retry };
+    }
+    throw error;
+  }
+}
+```
+
+该函数执行真实写入，仅用于已授权的新增意图。错误的 `execution` 说明执行到哪一步：`notStarted` / `rolledBack` 没有任何改动，`committed` 已生效，`unknown`（只出现在写入）可能已生效，此时抛出的是 `UnsV2OutcomeUnknownError`。`retry.safe` 表示可以用同一请求（同一幂等键）重发，`retry.afterMs` 是建议等待时间。`client.uns` 从不自动重试；unknown 时按指定 id 读取并核对业务内容，不能只凭记录存在就判定本次成功。
+
+recordTransactionExecute 用 opId/dependsOn 表达依赖；不要拆成若干普通请求后声称具备事务性。allowPartial 适用于支持它的普通数组写入，事务不接受。部分成功检查每项结果，修正后的失败项是新的业务请求，不能原样重放整个批次。
+
+recordLock 返回的 token 是租约凭据，更新/续租/解锁按原记录匹配；超时或租约失效不能继续假定持锁。只读响应中的 lock 状态不包含可用于写入的令牌。

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/delete.md

@@ -0,0 +1,53 @@
+# 删除记录与元数据
+
+记录删除仍使用专属数据接口：
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function deleteDevice(
+  collectionId: string, id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 })).data.items[0];
+  if (!current) throw new Error('记录不存在或不可见，未执行删除');
+  const receipt = await client.uns.recordDeleteOne({
+    collectionId, filter: { _id: id }, expectedRevision: current.revision,
+    dryRun: false, idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || String(receipt.data.deletedCount) !== '1') {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const after = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
+  if (after.data.items.length) throw new Error('删除有回执，但记录仍可见或已被恢复');
+  return { state: 'committed' as const, receipt };
+}
+```
+
+元数据使用 metadataDeleteOne/Many，或 metadataFindOneAndDelete 返回删除前对象。它们执行软删除，增加 revision，不隐式级联目录后代、引用对象或集合数据。引用约束与版本冲突必须处理，不能自行扩展删除范围。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function deleteCollection(
+  id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('集合不存在或不可见，未执行删除');
+  const receipt = await client.uns.metadataDeleteOne({
+    kind: 'collection', filter: { _id: id }, expectedRevision: current.revision,
+    dryRun: false, idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || String(receipt.data.deletedCount) !== '1') {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const deleted = await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id }, state: 'deleted' });
+  if (!deleted.data.value) throw new Error('删除有回执，但删除状态读回未确认');
+  return { state: 'deleted' as const, receipt, deleted: deleted.data.value };
+}
+```
+
+metadataDeleteMany 使用明确 filter 和 maxDocs。默认原子；超过上限整体拒绝，不会静默只删第一批。批量删除前可 dryRun。state 默认 active，删除对象通过 state=deleted 查询；all 同时包含两种状态。
+
+业务记录使用 recordDeleteOne/Many，传 collectionId 和明确 filter，编辑型流程同时传 expectedRevision。不要把元数据软删除解释成逐条删除该集合的 Record。Sample 的删除是独立的显式时间范围操作，具体影响遵循当前数据 API 契约。
+
+恢复见[恢复](restore.md)。未知写入结果保留原意图键，先按对象身份核对，不自动换键重试。

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/namespace.md

@@ -0,0 +1,38 @@
+# 目录、Topic 与元数据事务
+
+目录、Topic、Collection 使用同一套 metadata* 方法，通过 kind 指定类型。Source/Stream 的启停、连接和发布仍使用各自专用生命周期接口；不允许把系统任务、凭据或发布历史当作普通元数据修改。
+
+| 场景 | 方法 |
+| --- | --- |
+| 单条/批量新增 | metadataInsertOne / metadataInsertMany |
+| 单条/批量条件更新 | metadataUpdateOne / metadataUpdateMany |
+| 更新并读取原子结果 | metadataFindOneAndUpdate / metadataFindOneAndReplace |
+| 同 kind 混合写入 | metadataBulkWrite |
+| 跨 kind、有依赖的组合操作 | metadataTransact |
+| 软删除并返回原对象 | metadataFindOneAndDelete |
+| 按明确 ID 批量恢复 | metadataRestore |
+
+普通写操作只指定一个 kind。insertMany/updateMany/deleteMany/restore 固定原子执行；bulkWrite 默认 atomic=true，原子批次不接受 ordered=false。bulkWrite 显式 atomic=false 时 ordered=true 遇错停止，false 继续，并检查 results/errors。非原子执行有任一项已提交后失败时，`execution` 为 committed、`retry.safe` 为 false，错误的 data 是累计结果：序号小于 `nextIndex` 且不在 errors 里的操作已提交；有 `unknownUntil` 时 `[nextIndex, unknownUntil)` 结局未知，用同一个幂等键重试（不带键时只有按 id 的操作能先读回再续做，所以非原子批次始终带幂等键）；没有 `unknownUntil` 时从 `nextIndex` 续做。第一块就结局未知时 `execution` 为 unknown。批次最多 200 项。不要给所有对象套一个相同 expectedRevision：需要逐项版本检查时在 bulkWrite 中分别提供。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function createDirectoryAndTopic(
+  directoryId: string, topicId: string, collectionId: string, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  return client.uns.metadataTransact({
+    idempotencyKey: intentKey,
+    operations: [
+      { opId: 'directory', action: 'insertOne', kind: 'directory', id: directoryId,
+        data: { name: '设备目录', parentId: null } },
+      { opId: 'topic', action: 'insertOne', kind: 'topic', id: topicId, dependsOn: ['directory'],
+        data: { name: '设备视图', parentId: { ref: 'directory' }, viewMode: 'records', collectionId } },
+    ],
+  });
+}
+```
+
+transact 始终原子，结果通过 opId 对应输入；dryRun=true 校验，不预留 ID 或名称。正式执行仍重新检查。创建结果引用仅用于契约支持的关系字段，不能把任意字符串或脚本当引用。
+
+名称、父目录、Schema、引用与权限由服务端校验。移动不改变对象 ID；删除目录不隐式清空后代；删除 Topic 不删除所引用的 Collection。引用查询仍使用 references 专用方法。

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

@@ -0,0 +1,34 @@
+# 查询集合与记录
+
+| 方法 | 必要输入 | 返回 data |
+| --- | --- | --- |
+| metadataFind | kinds；可选 filter、sort、projection、page、state | items、pageInfo |
+| metadataFindOne | kind、filter；可选 state | value，未找到为 null |
+| metadataCount / metadataDistinct | kind/kinds 与查询条件；distinct 还指定 field | count / values、pageInfo |
+| collectionDescribe | collectionId | 集合结构和数据能力 |
+| recordFind | collectionId；可选 filter、sort、limit、cursor | items、pageInfo |
+
+元数据查询配置字段写 name、parentId；系统字段写 _id、_meta.kind、_meta.revision。返回资源的配置在 value.data 或 items[].data 中。state 为 active/deleted/all，默认 active。对象身份始终是 kind + id。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function readDevices(collectionId: string, client: Tier0Client = createClient()) {
+  const collection = await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: collectionId } });
+  if (!collection.data.value) throw new Error('集合不存在或不可见');
+  const records = await client.uns.recordFind({
+    collectionId, filter: { enabled: true }, sort: [['name', 1]], limit: 20,
+  });
+  return { definition: collection.data.value.data, items: records.data.items, pageInfo: records.data.pageInfo };
+}
+
+export async function listCollections(page = 1, client: Tier0Client = createClient()) {
+  return client.uns.metadataFind({
+    kinds: ['collection'], state: 'active', sort: [['_id', 1]], page: { mode: 'offset', page, size: 20 },
+  });
+}
+```
+
+按 pageInfo.hasMore/nextPage 继续元数据分页；不要把第一页当全量。recordFind 的游标循环见[数据工作流](data-workflows.md)。sort 是数组元组。
+
+以上 metadataFind/FindOne 示例用于 Workspace 集成（会话、personal / agent Key）。App 凭证不能调用 metadataFind/FindOne：用 dataAppContext 精确选择授权 alias，集合的 revision、indexStatus、ttl 也在其中。数据授权不等于元数据管理授权。网络/权限错误必须传播，不能用空数组掩盖错误。

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/restore.md

@@ -0,0 +1,39 @@
+# 恢复元数据与记录
+
+metadataRestore 接收 kind、items[{id,expectedRevision?}]，支持一个或多个明确 ID。revision 应从 state=deleted 的当前对象读取。恢复重新校验名称、父目录、Schema 与引用；不会恢复其他对象，冲突时原子批次回滚。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function restoreCollection(
+  id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const deleted = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id }, state: 'deleted' })).data.value;
+  if (!deleted) throw new Error('未找到待恢复集合');
+  const receipt = await client.uns.metadataRestore({
+    kind: 'collection', items: [{ id, expectedRevision: deleted.revision }], idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || String(receipt.data.restoredCount) !== '1') {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('恢复有回执，读回未确认');
+  return { state: 'committed' as const, receipt, current };
+}
+
+export async function restoreDevice(
+  collectionId: string, id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const receipt = await client.uns.recordRestore({
+    collectionId, ids: [id], dryRun: false, idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || !receipt.data.restoredIds.includes(id)) {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const found = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
+  if (!found.data.items[0]) throw new Error('恢复有回执，读回未确认');
+  return { state: 'committed' as const, receipt, current: found.data.items[0] };
+}
+```
+
+Record 恢复使用 recordRestore 的 ids（最多 100 条），重新校验当前 Schema 和有效唯一索引，冲突整批回滚。新增同 ID 或 upsert 不会隐式恢复对象。幂等键每个新意图独立。

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/update.md

@@ -0,0 +1,62 @@
+# 修改记录、元数据和 Schema
+
+元数据单条使用 metadataUpdateOne 或 metadataFindOneAndUpdate；后者原子返回 value，returnDocument 可选 before/after。批量相同更新使用 metadataUpdateMany；不同更新使用 metadataBulkWrite。完整替换使用 metadataReplaceOne/metadataFindOneAndReplace，replacement 是完整可写配置。
+
+update 首版支持 $set/$unset/$setOnInsert。字段使用裸配置路径；_id/_meta 为只读。写前读取 revision，编辑页面携带 expectedRevision，冲突后重新比较。单条 upsert 需明确 _id 等值条件，新增内容满足完整创建约束；同 ID 的软删除对象必须显式恢复。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function renameCollection(
+  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('集合不存在或不可见');
+  return client.uns.metadataFindOneAndUpdate({
+    kind: 'collection', filter: { _id: id }, expectedRevision: current.revision,
+    update: { $set: { name } }, returnDocument: 'after', upsert: false, idempotencyKey: intentKey,
+  });
+}
+```
+
+修改 Schema 时先构造完整 recordSchema，再用 $set 更新该字段。它不迁移已有记录，必须兼容保留数据与引用。没有修改的 sampleSchema/indexes 保持原值。先 dryRun，再用独立正式意图键提交。
+
+```ts
+import { createClient, type Tier0Client, type Schema } from '@tier0/sdk-v2';
+
+export async function replaceRecordSchema(
+  id: string, recordSchema: Schema, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('集合不存在或不可见');
+  const request = { kind: 'collection' as const, filter: { _id: id },
+    expectedRevision: current.revision, update: { $set: { recordSchema } } };
+  const preview = await client.uns.metadataUpdateOne({ ...request, dryRun: true });
+  if (preview.data.status !== 'validated') throw new Error('Schema 预检未通过');
+  return client.uns.metadataUpdateOne({ ...request, dryRun: false, idempotencyKey: intentKey });
+}
+```
+
+业务记录仍使用 recordUpdateOne：传 collectionId/filter/update，按需携带 expectedRevision。metadataUpdateOne 不能更新 Record 的业务内容。matchedCount 和 modifiedCount 不等价；值未变化时 modifiedCount 可为 0。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function renameDevice(
+  collectionId: string, id: string, name: string, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 })).data.items[0];
+  if (!current) throw new Error('记录不存在或不可见');
+  const receipt = await client.uns.recordUpdateOne({
+    collectionId, filter: { _id: id }, expectedRevision: current.revision,
+    update: { $set: { name } }, upsert: false, dryRun: false, idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || String(receipt.data.matchedCount) !== '1') {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const after = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
+  if (after.data.items[0]?.data.name !== name) throw new Error('读回名称与目标不一致');
+  return { state: 'committed' as const, receipt, current: after.data.items[0] };
+}
+```