Skip to content

Overview

This content is not available in your language yet.

0. 规范语言

本文中的规范关键字（MUST / SHOULD / MAY 等）按 conformance/normative-language.md 解释；仅大写形式具规范约束力。

1. 目标

Arkret 的核心数据模型是一张以 Realm 为边界、以标准对象和开放 Morph 共同组成的可审计协作图。本目录定义协作图中所有标准对象的语义、字段、行为与互相之间的关系。

阅读建议：

  • 第一次接触请按本文 §3 设计原则与 §2 typed-id 一览建立总览。
  • 字段细节、必填性、枚举值集中在 common-fields.md（公共字段）与各对象自己的”字段”小节。
  • 每个对象在 models/ 下都有唯一权威文件；文件之间不重复 normative 规则，只在必要处交叉引用。

2. Typed ID 一览

每个 Arkret 对象的种类由 id 的 typed-id 前缀（ak:<kind>:）唯一决定，canonical object 上不再单独写 type 字段。typed-id kind 的完整集合与 wire form 以 artifacts/registry/id-kind-registry.json（生成自 contract-registry）为准；本表仅把协作图核心对象索引到详细文档，不是完整 kind 清单。

DID 的使用边界见 common-fields.md §4.1：DID 标识 actor / principal / issuer / service 等主体，不替代 ak:<kind>: 对象 ID。设备不是主体 DID，使用 device_id + principal 下的 authorization。

2.1 协作图核心对象

Typed ID对象说明详情
ak:realm:Realmsecurity / sync / auth / E2EE 边界realm-and-space.md
ak:circle:CircleRealm 内子事件 / 子消息边界（子集成员 / 独立 history / 投递裁剪；可选独立 MLS group），对象通过 scope_circle_id 引用circle.md
ak:sidecar:Agent Sidecarcontroller 的个人 AI 私有工作区；Event-derived ID，native scope，参与者由 controller + 当前 Realm 内的 active owned Agents 派生sidecar.md
ak:space:Space产品结构容器与导航节点（project / folder / board / list / section …），通过 realm_id 解析安全边界realm-and-space.md
ak:strand:Strand统一协作主对象（task / decision / incident / channel …）strand-and-message.md
ak:message:MessageStrand discussion track 时间线消息strand-and-message.md
ak:morph:Morph开放形态对象，承载扩展业务类型morph.md
ak:relation:Relation一等关系对象（contains / replies_to / depends_on …）relation.md
ak:actor_profile:Actor ProfileActor 在协作图中的展示镜像actor.md
ak:view:View投影定义（看板 / 列表 / 时间线 / graph / document …）views.md
ak:event:Event签名事件，reducer 输入与审计事实event-and-patch.md

2.2 治理对象

Typed ID对象说明详情
ak:policy:Policyaccess / encryption / retention / federation / moderation 等策略governance-objects.md
ak:capability:Capability Definitionabstract capability definition reference（非签名 grant；签名 grant 用 ak:grant:）。真源见 id-kind-registry.json capability 条目。governance-objects.md
ak:grant:Capability Grant授权委派governance-objects.md
ak:invite:InviteRealm 加入引导governance-objects.md
ak.schema.*Schema标准对象 / Morph type / facet / event 的结构与约束governance-objects.md

2.3 派生 / 私有对象

派生对象不是 canonical truth，由 client / SDK 从 Event 集合本地计算；schema 仅用于 wire 表示。

Typed ID对象说明详情
ak:notification:Notificationinbox projectionprivate-objects.md

Read Cursor（actor-private 已读位置，private-objects.md）没有 typed ID：身份是 (actor_id, realm_id, read_scope) 三元组，ak.read_cursor.advance 的 id_source 为 not_an_object_id。

2.4 内容 / 媒体 / 扩展对象

Typed ID对象说明详情
ak:blob:Blob由 Blob Store 管理的数据，不参与协作图归约。两种形态：ak:blob:<uuid> 是 metadata row id；ak:blob:sha256:...（sha256:<hex>）是内容寻址特殊形态（详见 id-kind-registry.json）。extension-objects.md
ak:applet:Appletbot / bridge / portal / 集成服务（extension profile）extension-objects.md
Agent runtimeAgent外部 agent 协议互通运行时extension-objects.md

2.5 辅助标识符

Typed ID对象说明
“、ak:cursor:、ak:realm_commit:状态 / 同步原语不是协作图对象；语义见 authz/event-auth-state-resolution.md、sync/operations-sync.md 与 conformance/encoding.md

字段级、必填性、枚举值与 wire 约束统一以 common-fields.md 与各对象文件中的字段表为准。Schema 引用见 artifacts/schemas/，event/operation registry 见 artifacts/registry/。

2.6 对象关系总览

下图把核心 typed-id 之间的归属、容纳、引用、投影关系画成一张图。ak:event: 是事实根，所有共享对象都是 Event 集合在某个 fixed reducer semantics 下的物化结果。

flowchart TB
    Event["ak:event:<br/>签名事件（事实根）"]

    subgraph SP ["ak:realm: — security / sync / auth / E2EE 边界"]
        direction TB
        Space["ak:space:<br/>kind=board / list / ..."]
        Strand["ak:strand:"]
        Morph["ak:morph:"]
        Msg["ak:message:<br/>(discussion 时间线)"]
        Rel["ak:relation:"]

        Space -- "contains" --> Strand
        Space -- "parent_space_id（同 Realm）" --> Space
        Strand -- "tracks.discussion" --> Msg
        Rel -. "from_ref / to_ref" .-> Strand
        Rel -. "from_ref / to_ref" .-> Morph
        Rel -. "from_ref / to_ref" .-> Space
    end

    Circle["ak:circle:<br/>(Realm 内子事件边界)"]
    Strand -. "scope_circle_id<br/>（窄化 effective scope）" .-> Circle

    View["ak:view:<br/>投影定义（不持有真相）"]
    View -. "投影" .-> Strand
    View -. "投影" .-> Space
    View -. "投影" .-> Msg

    Event ==> SP
    Event ==> Circle

读图要点：

  • 实线箭头是结构归属或容纳关系；虚线是引用 / 投影 / scope 窄化。
  • ak:realm: 是 federation/identity 硬边界——federation、policy、capability registry、Realm-default MLS 都以它为根。ak:space: 永远不是边界，Space metadata 由 realm_id 指向的 home Realm 授权。
  • ak:circle: 是 Realm 内的子事件 / 子消息边界——子集成员 / 独立 history / 投递裁剪；在 E2EE Realm 或 policy 要求下还拥有独立 MLS group。Strand.scope_circle_id 指向 Circle 表示整个 Strand（所有 track）落在该 Circle scope。
  • ak:sidecar: 是独立个人 AI 工作区和原生安全 scope，不是 Circle profile，不复用或隐藏 Circle 对象、membership 与 lifecycle。
  • ak:relation: 是一等对象，跨对象语义 MUST 通过 Relation 表达，不藏在字段里。
  • ak:view: 拥有投影定义的真相，但不持有被投影对象的协作事实。
  • Discussion 想要独立 membership / history visibility / 投递裁剪或 E2EE 时，整个 Strand 通过 scope_circle_id 落在一个 Circle；v1 不定义 per-track 安全边界。

3. 设计原则

3.1 Realm 边界与 Space 容器

容器选型的 normative 判定顺序以 ../overview/architecture.md §2.0 为准；本节仅作为模型目录导览，具体字段与 reducer 规则仍以各对象专属文件为准。

每个 ak:realm: 都是 security/sync/auth/E2EE 硬边界——复制、权限、schema、policy、membership、history visibility、加密、federation policy 都以它为根。Realm 不承担产品导航树职责：结构性分组、项目、folder、看板、列、泳道、calendar bucket 等由独立的 Space 对象（ak:space:）承担，Space 永远不形成独立边界。

security_class=high_assurance 是 Realm 的可选标签，进一步收紧 federation policy 与默认审计/E2EE 选项。

Realm 之间 MAY 通过 ak.realm.link 形成显式 link graph（governance、discoverability、confidential_extension、mirror 等），但 v1 不定义通用 Realm hierarchy。membership、capability、history visibility、schema、policy 和 encryption key 不因 link 级联；任何继承都必须由目标 Realm 显式声明。详细规则见 realm-links.md。

Space 层级通过 Space 自己的 parent_space_id + ak.space.parent 表达，MUST 位于同一 Realm 内；不传播 Circle 可见性或对象 capability。跨 Realm 展示使用 View / 普通引用。详细规则见 space-hierarchy.md。

3.2 Strand 承载主语义

同一个协作主题由一个 Strand 表达；track primary 解析规则与 track 配置决定默认入口和能力面。

标准对象本身表达主语义：

  • strand：统一协作主对象。它承载 metadata.title / metadata.summary / content 等基础字段，并通过 track primary 解析规则决定默认进入哪个 track。
  • message：Strand discussion track 中的消息。
  • morph：开放形态对象，用于业务扩展、未知类型和实验对象。
  • space：Realm 内部的结构容器（kind=board / kind=list / 其他 profile 注册的形态）。

标准对象 MAY 暴露 schema/profile 已声明的 facets 来辅助展示或查询，但它的核心职责不依赖 facets 才成立。实现不得要求标准对象先声明 facet 才能承认其主语义。

3.3 Morph 是开放对象

morph 表示协议未固化为标准类型的协作对象，适合插件、未来标准类型实验、外部系统镜像、低频弱互操作扩展数据。

Morph 的可见能力可以由 Realm schema / Morph profile 声明，并通过 facets 暴露给 View、UI、本地搜索或插件。实现遇到未知标准类型 SHOULD fail closed；遇到未知 Morph facet SHOULD 保留数据，但不得让未知 facet 绕过 schema、capability、policy 或 encryption 约束。

Facet 字符串本身不是规范性 reducer 或授权来源。任何会改变写入权限、状态转换、排序、包含关系、事件有效性或跨实现 wire 行为的能力，MUST 由明确 schema/profile/event kind/capability action 定义。详情见 morph.md。

3.4 Relation 是一等对象

跨对象语义 MUST 使用 relation 表达，而不是藏在对象字段里。Relation 连接的是对象引用：标准字段 from_ref / to_ref 指向 canonical 对象的 ak:<kind>: typed ID，合法端点 kind 的权威集合（realm / space / actor_profile / strand / message / morph / relation / event / view / blob）见 relation.md §1 与 relation.schema.json。Actor 端点 MUST 直接使用该 actor 的完整结构化 ActorId（包括 Station 归属），MUST NOT 使用裸 DID 或字符串化 JSON；ak:actor_profile: 只表示展示镜像对象，不能代替 Actor 端点（见 common-fields.md §4.1）。

跨 Realm 引用规则、结构性 Relation 的本地约束（如 contains / belongs_to 不可跨 Realm）见 relation.md。

3.5 Event 是事实

所有协作变化最终都落为签名 event。Event 是审计根和 reducer 输入。当前态只是 Event 集合在某个 fixed reducer semantics 下的物化结果。详情见 event-and-patch.md。

3.6 View 是投影定义

view 是一等协议对象，但它拥有的是投影定义的真相，而不是被投影对象的协作事实。它定义查询、过滤、排序、分组、renderer、布局、可见字段和共享 saved view 配置。

View 不得发明对象能力，也不得持有对象状态的唯一副本；对象能力来自对象类型、schema/profile 和 capability，facets 只作为已声明能力的查询与投影 hint。详情见 views.md。

3.7 Schema 演进

标准类型演进 MUST 遵守：

  • 新字段优先 optional。
  • 既有字段不得静默改变语义。
  • reducer 和客户端 MUST 保留 schema 允许但实现未识别的字段（canonical envelope 层 schema 未声明的字段按 event-and-patch.md §2.2 拒绝），但 MUST NOT 让这些字段绕过 capability、schema、policy 或加密约束。
  • UI 遇到未知 Morph type SHOULD 降级为 generic Morph card。
  • 标准对象不得阻止 Realm 定义自定义 Morph type。

4. 阅读路径（Reading Paths）

按目标层面索引：

关注层面起点
协作图整体结构 / 标准对象一览本文 §2-§3
公共字段、lifecycle、reducer 总则common-fields.md
Realm 边界、看板 / 列 / 容器、位置语义realm-and-space.md
Circle 子事件 / 子消息边界、成员范围、独立 MLS 与 sub-authority commitcircle.md
Agent Sidecar 独立对象、派生 access、backing scope 与 private contextsidecar.md
Strand / track / discussion / Messagestrand-and-message.md
Morph 类型、facets、扩展morph.md
Relation 基数、跨 Realm、冲突relation.md
Actor、Actor Profileactor.md
Schema / Policy / Capability Grant / Invitegovernance-objects.md
Read Cursor / Notificationprivate-objects.md
Event Envelope / Proof / Patch / Receipt / reducerevent-and-patch.md
Applet / Agent / Blobextension-objects.md
Content Block（消息正文 / 富文本 / 媒体）content-types.md
投影 / 看板 / 时间线 / graph / document Viewviews.md
Realm link graph、显式继承、治理关系realm-links.md
Space 产品结构层级、跨 Realm 导航space-hierarchy.md

5. 规范性引用

  • 标准 event type 注册表见 ../conformance/schema-registry.md。
  • Reducer conformance vector 见 ../conformance/conformance-vectors.md。
  • Schema evolution 测试见 ../conformance/conformance-profiles.md。
  • authority-commit projection / capability 校验规则见 ../authz/event-auth-state-resolution.md。