# Type Definition

创建、发布并通过 Bundle 版本范围依赖使用跨工作区共享类型。

Type Definition 是平台顶层资源，不属于任何 Bundle 或 Module。工作区拥有可编辑草稿；平台为资源分配
稳定 UUID。草稿发布为精确 Semantic Version 后，版本内容不可覆盖、不可删除，并立即对当前平台部署中的
所有工作区公开。

Type Definition 没有安装、升级、卸载或 Runtime 台账。Bundle 声明可接受的发布版本范围，Module 只引用
稳定的具体类型成员。

## 引用格式

```text
baijimu-type://environmentKey/typeDefinitionId#TypeName
```

例如：

```text
baijimu-type://baijimu/8f5a8fd4-c074-4eab-8c58-6587bb35384a#ProductProvider
```

- `environmentKey` 是产生定义的平台部署身份。
- `typeDefinitionId` 是平台分配的稳定 UUID，不使用工作区 ID、Bundle ID 或可变名称代替。
- 成员引用不携带版本、版本范围或 `latest`。
- `TypeName` 必须存在于 Bundle 依赖范围允许的所有已发布版本中。

## 创建和发布

管理前端的“工作区管理 → 类型定义”可以创建草稿、编辑完整 document、检索公开目录和发布版本。

CLI 示例：

```bash
baijimu type-definition create my-workspace \
  --type-key product-provider \
  --definition @product-provider.json

baijimu type-definition publish my-workspace \
  8f5a8fd4-c074-4eab-8c58-6587bb35384a 1.0.0

baijimu type-definition public --query product --kind INTERFACE
```

发布新版本不会修改历史版本。已公开定义需要演进时，先更新工作区草稿，再选择符合兼容性语义的新版本号。

## document

```json
{
  "schemaVersion": "1.0.0",
  "kind": "INTERFACE",
  "rootType": "ProductProvider",
  "types": {
    "ProductProvider": {
      "@type": "Interface",
      "methods": {
        "list": {
          "returnType": {
            "@type": "Array",
            "items": { "@type": "Ref", "typeName": "Product" }
          }
        }
      }
    },
    "Product": {
      "@type": "DataType",
      "expression": {
        "@type": "Object",
        "properties": {
          "sku": {
            "type": { "@type": "Primitive", "name": "string" },
            "required": true
          }
        }
      }
    }
  }
}
```

Type Definition document 内部成员使用 `@type: "Ref" + typeName`，同一次发布中的成员可以形成完整引用图。
跨 Type Definition 的 document 引用仍属于 Type Definition 发布契约，不使用 Module 或 Bundle 的成员引用字段代替。

## Bundle 和 Module 的边界

Bundle 在 `typeDefinitionDependencies` 中声明稳定 locator 和版本范围，例如：

```json
{
  "locator": {
    "environmentKey": "baijimu",
    "typeDefinitionId": "8f5a8fd4-c074-4eab-8c58-6587bb35384a"
  },
  "semanticVersion": "^1.2.3"
}
```

版本范围使用 Cargo `VersionReq` 语义，每个边界必须写完整 `MAJOR.MINOR.PATCH`。不接受通配符、缺段版本、
`latest` 或 `=1.2.3` 这类精确锁定。该范围只用于编辑器筛选和 Bundle 发布校验，不产生 `resolvedVersion`，
也不进入安装资源计划或 Runtime ledger。

Module 可以在接口、属性或方法类型中使用无版本成员 URI。Module Version 保存这些稳定引用，不声明
`typeDefinitionDependencies`，也不解析、展开或物化某个精确 Type Definition版本。

Module 配置界面从所属 Bundle 的依赖范围加载可选类型。冻结 Bundle 时，平台汇总其中所有 Module 的成员引用，
确认每个引用都有同 locator 的 Bundle 依赖，并校验依赖范围内的已发布版本均导出相应成员。缺少依赖、没有
匹配版本或成员不兼容时拒绝发布。