doxum 0.1.1

package/skills/doxum-runtime/references/invariants.zh-CN.md

@@ -0,0 +1,97 @@
+# Doxum Runtime 不变量
+
+修改或审查 mutation、addressing、impact、notification、history、tree 或 projection 前应阅读本页。这些是设计边界，而不是可选的代码风格。
+
+## 唯一的 canonical 写入权威
+
+`createDocument` 拥有 canonical mutable document state。新的 mutation 行为只能通过 `runtime.update`、`runtime.apply` 或 `runtime.replace`。writer 只是向 mutation session 产生 operation，而不是绕过 runtime 修改对象的出口。
+
+绝不能新增：
+
+- 并行的可写 document cache；
+- 在 runtime 外编辑 document state 的 reducer；
+- 由调用方手工同步的 view；
+- 绕过 decode、normalization、inverse 记录、rollback、impact、history 或 notification 的 operation 执行路径。
+
+## Transaction 生命周期与原子性
+
+transaction callback 必须同步。reader 与 writer 只在 callback 执行期间有效。`async` callback、保存 reader/writer 供后续使用、嵌套写入，以及 notification 期间写入都会破坏 runtime 边界。
+
+每个 session 都是原子的。若一个 operation 在之前已有状态变更后被拒绝，session 之前的全部工作都必须回滚。callback 抛错也会回滚，然后将原始错误继续抛出。预期中的拒绝应该通过返回结果表示，而不是异常协议。
+
+## 保持引擎问题与应用问题分离
+
+| 问题                                      | 所有者           | 结果形状                                        | 正确处理方式                                 |
+| ----------------------------------------- | ---------------- | ----------------------------------------------- | -------------------------------------------- |
+| malformed、无法解析或语义无效的 operation | Doxum engine     | `source: 'mutation'` 的 `MutationIssue`         | 检查 rejected operation/transaction result。 |
+| 应用业务规则或校验                        | Application      | `source: 'application'` 的 `DocumentDiagnostic` | 使用 `tx.report` 或 `tx.reject`。            |
+| callback 缺陷或意外失败                   | Application code | rollback 后抛出的 error                         | 在 transaction 外修复或处理异常。            |
+| processor、flush 或 listener 失败         | Observer         | committed result 上的 `observerErrors`          | 修复 observer；不要重放已提交的 write。      |
+
+不要再创建笼统的 `invalid` status，不要把全部 error 字符串化为同一个形状，也不要将 notification failure 变成 mutation rejection。Mutation issue code 是封闭的公共词汇，必须保持精确。
+
+## Schema 拥有 addressing 与 selector
+
+schema 定义 operation 与 selector 的合法语义地址。address resolution 结合 schema 结构和当前 document state，这对于 collection entry 和 variant branch 都是必要的。
+
+长期使用的 target 应由 `schema.value(...)` 与 `schema.collection(...)` 创建。runtime 的地址域使用 `runtime.address`；target 的 identity 与 bucket 使用导出的 `target` namespace。不要新增 string-path parser、另一种 address type、自定义 selector ID 或独立的 impact-target equality helper。
+
+## Operation 只有一条 pipeline
+
+外部 operation 输入遵循如下顺序：
+
+```text
+decode -> normalize -> resolve -> execute -> inverse + journal -> publish
+```
+
+`apply` 是不可信 operation envelope 的边界。executor code 看到输入前必须完成 decode；随后要归一为唯一 canonical operation shape、按 schema resolve，并且只能整体 publish 或整体 rollback。每个 committed operation 都需要精确的 inverse data 与精确的 impact。
+
+本地应用行为应使用 writer，而不是手工拼 operation object。直接构造 operation 适用于边界 adapter、fixture、migration 和有意的 replay。
+
+## 所有权必须明确
+
+- `initial` 在成为 canonical state 前会被 clone。
+- 普通 operation 中的结构化 payload 会转移到 canonical state。提交后仍修改它，可能会修改 canonical data。
+- commit 与 history 的 operation payload 是不可变 snapshot。
+- 已发布的 diagnostic 与 selector address 会被复制并冻结。
+- tree replacement snapshot 会先校验并 clone。
+
+不要承诺 Doxum 有意进行 payload transfer 的地方存在深度不可变性。调用方若要保留可变所有权，应在提交前自行 clone。
+
+## Tree 完整性是整个 document 的完整性
+
+每个存在的 tree 必须为空，或恰好只有一个 root；从 root 可完整到达所有节点、无环、无重复 child 引用，且 parent/child 双向一致。initial state 与 replacement snapshot 会完整检查，本地 tree operation 则增量维持它。
+
+不能接受不连通 forest、orphan node、非 root move 到无 parent、将 root 挂到另一节点之下，或直接编辑 tree 的内部 record。tree operation 被拒绝时，整个 transaction 必须保持不变。
+
+## Impact 与 notification 描述已提交状态
+
+每次 commit 都发布一个 `DocumentImpact`；它不是让调用方修改的 mutable change log。value impact 使用 `affects(target)` 判断；collection impact 精确报告 added、removed、updated 和 order change，或在 replacement/subtree reset 后报告 `reset`。
+
+notification 顺序是可观察行为：
+
+```text
+commit -> materialized processors -> processor flushes -> targeted listeners -> root listeners
+```
+
+update 与 notification 窗口中禁止写入。processor、flush 和 listener error 会被收集，但 committed document、revision 与 history 必须保持稳定。
+
+## 派生状态应声明，而不是由调用方同步
+
+`CollectionView` 从一个已声明的 collection 派生，并增量维护 ids、keyed values 和惰性 aggregate array。`MaterializedView` 从 document read、跟踪到的 impact dependency 和可选的更早 materialized source 派生一个值。materialized view 只能依赖同一 runtime 中比它更早创建的 view。
+
+不要把 derived value 缓存在 canonical document state 中，除非它本来就是领域数据。不要让 UI 手工将变更推入 view。view 与 subscription 都应随 owner dispose。
+
+## Framework 与产品边界
+
+`core` 必须保持 framework-neutral。`doxum/react` 是从 core 到 React 的单向 adapter；core 不能 import React 或 UI 概念。Doxum 有意不决定 persistence format、网络同步、authorization、retry、acknowledgement、ordering 或 conflict resolution。应用必须在 apply operation 或 replace snapshot 前做出这些决策。
+
+## 改动检查清单
+
+runtime 相关改动交付前检查：
+
+- 每一次 canonical write 是否仍经由 `createDocument`？
+- 适用时，是否测试了成功、rejected rollback、inverse history 与 impact/subscription 行为？
+- tree 与 collection 路径是否避免了意外的全量 document copy 或 traversal？
+- 公共生命周期语义变化时，是否更新了 README 与 architecture guide？
+- 过时的 protocol type、局部 helper 和重复的 address/target 解释是否被删除，而不是为了兼容继续保留？

package/skills/doxum-runtime/references/patterns.en.md

@@ -0,0 +1,287 @@
+# Doxum Patterns
+
+Read this reference when implementing Doxum application code. It is organized by
+the decisions that preserve the runtime model, rather than by an exhaustive
+list of exported symbols.
+
+## Model data by its mutation semantics
+
+| Need                            | Schema node                | Canonical value     | Writer behavior                              |
+| ------------------------------- | -------------------------- | ------------------- | -------------------------------------------- |
+| One scalar or immutable leaf    | `field<T>()`               | `T`                 | `set`, and `clear` for an optional field     |
+| Nested named fields             | `object({ ... })`          | object              | child writers                                |
+| Tagged structural alternatives  | `variant('kind', { ... })` | tagged object       | `replace` the complete branch value          |
+| One structured entity           | `single(entity)`           | object              | child writers                                |
+| Ordered entities                | `table(entity)`            | `{ ids, byId }`     | `create`, `item`, `remove`, `move`           |
+| Unordered entities              | `map(entity)`              | id record           | `create`, `item`, `remove`                   |
+| Scalar record                   | `record<Id, T>()`          | complete record     | `set`, `delete`, `replace`                   |
+| Sparse scalar dictionary        | `dict<Key, T>()`           | partial record      | `set`, `delete`, `replace`                   |
+| Ordered scalar/structural items | `list({ keyOf })`          | array               | `insert`, `move`, `remove`, `replace`        |
+| One rooted hierarchy            | `tree<T>()`                | `{ rootId, nodes }` | `insert`, `move`, `remove`, `set`, `replace` |
+
+Use a table when ordering is product-visible. Do not use a map plus a separate
+array of ids: that creates two mutation protocols and two sources of order.
+Use a list only when every item has a stable, unique application key; never use
+the current index as `keyOf`.
+
+```ts
+import { field, list, map, object, schema, table, tree } from 'doxum';
+
+type Tag = { id: string; name: string };
+
+const note = object({ body: field<string>() });
+const documentSchema = schema({
+  notes: table(note),
+  tags: list<Tag>({ keyOf: tag => tag.id }),
+  collaborators: map(object({ name: field<string>() })),
+  outline: tree<{ title: string }>(),
+});
+```
+
+## Local domain command: read, validate, write
+
+Keep a domain command inside one transaction when all of its changes must
+succeed or fail together. Read before creating operations when a business rule
+depends on current state; call `tx.reject` for a blocking application rule.
+
+```ts
+function completeTask(id: string) {
+  return runtime.update(tx => {
+    const task = tx.read.tasks.get(id);
+    if (!task) {
+      tx.reject({
+        source: 'application',
+        code: 'task-not-found',
+        message: `Task '${id}' does not exist.`,
+        address: ['tasks', id],
+      });
+    }
+    if (task.completed.get()) return { changed: false };
+
+    tx.write.tasks.item(id).completed.set(true);
+    tx.report({
+      source: 'application',
+      code: 'task-completed',
+      message: 'Task marked complete.',
+      address: ['tasks', id],
+    });
+    return { changed: true };
+  });
+}
+```
+
+`tx.report` does not reject the transaction. It is suitable for warnings,
+audit-oriented feedback, or application messages that should accompany a valid
+commit. `tx.reject` stops the transaction by returning a rejected result to the
+outer caller. Neither is a substitute for malformed-operation handling:
+engine failures are `MutationIssue` values supplied by Doxum.
+
+## Apply external operations at one boundary
+
+Keep serialization, authorization, network ordering, and conflict policy in an
+application adapter. Once that adapter decides a batch may be applied, pass the
+whole batch to Doxum.
+
+```ts
+async function receiveRemote(batch: unknown) {
+  // Authenticate, order, de-duplicate, and choose conflict policy here.
+  const result = runtime.apply(batch, {
+    source: 'remote',
+    history: false,
+  });
+
+  if (result.status === 'rejected') {
+    logRejectedOperations(result.issues);
+    return;
+  }
+  if (result.status === 'committed') reportObserverErrors(result.observerErrors);
+}
+```
+
+The cast above belongs only at a dynamic boundary whose runtime input is
+actually unknown. Keep it there; do not loosen operation types throughout the
+application. Doxum still validates malformed envelopes and semantic invalidity
+before publishing a commit.
+
+Use `replace` only for a new, trusted canonical snapshot. It produces reset
+impact and invalidates local history. It is not a convenient way to express a
+small change.
+
+## Place ordered entries with anchors
+
+Tables and lists use one `DocumentAnchor` vocabulary:
+
+```ts
+{
+  at: 'start';
+}
+{
+  at: 'end';
+}
+{
+  before: 'other-id';
+}
+{
+  after: 'other-id';
+}
+```
+
+Use anchors instead of calculating indices in application code. They name the
+domain position, let Doxum validate missing references, and keep table, list,
+and operation replay semantics aligned.
+
+```ts
+runtime.update(tx => {
+  tx.write.tasks.create({ id: 'review', value: newTask }, { before: 'publish' });
+  tx.write.tags.insert({ id: 'urgent', name: 'Urgent' }, { at: 'start' });
+  tx.write.tags.move('urgent', { after: 'planning' });
+});
+```
+
+## Work with trees as one invariant
+
+A Doxum tree is either empty or a single connected root. Its `nodes` maintain
+reciprocal parent/child links, unique children, full reachability, and no
+cycles. Root replacement validates the whole snapshot; local writers preserve
+the invariant incrementally.
+
+```ts
+runtime.update(tx => {
+  tx.write.outline.insert('root', { title: 'Project' });
+  tx.write.outline.insert('plan', { title: 'Plan' }, 'root');
+  tx.write.outline.move('plan', 'root', 0);
+  tx.write.outline.set('plan', { title: 'Plan release' });
+});
+```
+
+Create the root with no `parentId` only when the tree is empty. Once a root
+exists, every inserted node needs an existing parent. Do not move a non-root
+node to `undefined`, re-parent the root, or directly edit `{ rootId, nodes }`
+outside a validated `tree.replace` or runtime `replace` snapshot.
+
+## Select and subscribe with the domain target
+
+Create selectors once with their owning schema. This creates a stable public
+contract for subscriptions and impact interpretation.
+
+```ts
+const notes = documentSchema.collection(path => path.notes);
+const body = documentSchema.value(path => path.notes.item('a').body);
+
+const unsubscribe = runtime.subscribe([notes, body], commit => {
+  if (commit.impact.affects(body)) refreshNoteUI();
+
+  const change = commit.impact.collection(notes);
+  if (change.kind === 'incremental' && change.updated.has('a')) refreshRow('a');
+});
+```
+
+Use `target.same(left, right)` only when you need to compare two impact targets
+as values. Use `target.address`, `target.id`, `target.belongs`, and
+`target.bucket` rather than duplicating their interpretation in a framework
+adapter or local helper.
+
+## Build a collection view for mapped rows
+
+Use a collection view when a table or map needs a reusable read model. Its
+mapping callback can read the entry's typed fields; `isEqual` lets the view
+retain a previous mapped value when a remapped row is semantically unchanged.
+
+```ts
+const notes = documentSchema.collection(path => path.notes);
+
+const noteSummaries = createCollectionView({
+  runtime,
+  source: notes,
+  map: (id, note) => ({ id, preview: note.body.get().slice(0, 80) }),
+  isEqual: (left, right) => left.id === right.id && left.preview === right.preview,
+});
+
+const stop = noteSummaries.item('a').subscribe(() => rerenderRow('a'));
+const all = noteSummaries.all.current();
+```
+
+Do not make callers push changes into the view. It listens to its declared
+source and recomputes from runtime state. Dispose `noteSummaries` and `stop`
+with the UI or service that owns them.
+
+## Build a materialized aggregate or index
+
+Use a materialized view when you own an aggregate that can update from a
+commit. During `update`, inspect the impact through the provided `impact`
+object. That records the actual dependencies, so future unrelated commits can
+skip this update.
+
+```ts
+const notes = documentSchema.collection(path => path.notes);
+
+const noteCount = createMaterializedView(runtime, {
+  build: ({ read }) => ({
+    value: read.notes.ids().length,
+    update: ({ impact, read }) => {
+      const change = impact.collection(notes);
+      if (
+        change.kind === 'incremental' &&
+        change.added.size === 0 &&
+        change.removed.size === 0 &&
+        change.updated.size === 0 &&
+        !change.orderChanged
+      ) {
+        return { kind: 'unchanged' };
+      }
+      return {
+        kind: 'changed',
+        value: read.notes.ids().length,
+        change,
+      };
+    },
+  }),
+});
+```
+
+Return `rebuild` if local incremental logic cannot safely handle a commit.
+Views created later can name earlier views in `sources`; Doxum processes that
+graph in creation order and flushes it before external listeners observe the
+commit.
+
+## Bind read models in React
+
+For a direct document read, use `useDocumentSelector`. It tracks paths and
+collection entries read during each selector execution, including dynamic
+dependencies.
+
+```tsx
+function Note({ id }: { id: string }) {
+  const body = useDocumentSelector(runtime, read => read.notes.get(id)?.body.get());
+  return <p>{body ?? 'Missing note'}</p>;
+}
+```
+
+For an existing read model, use its narrower hook:
+
+```tsx
+function NoteRow({ id }: { id: string }) {
+  const summary = useReadable(noteSummaries.item(id));
+  return <p>{summary?.preview}</p>;
+}
+
+function UndoButton() {
+  const history = useHistory(runtime.history);
+  return (
+    <button disabled={history.undoDepth === 0} onClick={() => history.undo()}>
+      Undo
+    </button>
+  );
+}
+```
+
+Keep selectors pure. They should read Doxum state and calculate a value; do not
+write, subscribe manually, or cause I/O while a selector is running.
+
+## Test the behavior that changes
+
+For a mutation change, cover the successful commit, rejected partial batch
+rollback, inverse/history result, and relevant impact or subscription outcome.
+For a projection, cover unrelated commits, dynamic dependencies, stable
+references where expected, and disposal. For large tables, lists, and trees,
+add a regression test that proves unrelated data is not copied or traversed.

package/skills/doxum-runtime/references/patterns.zh-CN.md

@@ -0,0 +1,240 @@
+# Doxum 模式参考
+
+实现 Doxum 应用代码时阅读本页。它按能保持 runtime 模型正确的决策组织，而不是机械穷举所有导出符号。
+
+## 按修改语义建模数据
+
+| 需求                 | Schema node                | Canonical value     | Writer 行为                                  |
+| -------------------- | -------------------------- | ------------------- | -------------------------------------------- |
+| 一个标量或不可变叶子 | `field<T>()`               | `T`                 | `set`；optional field 还可 `clear`           |
+| 命名的嵌套字段       | `object({ ... })`          | object              | 子 writer                                    |
+| 带 tag 的结构分支    | `variant('kind', { ... })` | tagged object       | `replace` 完整分支值                         |
+| 一个结构化实体       | `single(entity)`           | object              | 子 writer                                    |
+| 有序实体             | `table(entity)`            | `{ ids, byId }`     | `create`、`item`、`remove`、`move`           |
+| 无序实体             | `map(entity)`              | id record           | `create`、`item`、`remove`                   |
+| 标量 record          | `record<Id, T>()`          | 完整 record         | `set`、`delete`、`replace`                   |
+| 稀疏标量字典         | `dict<Key, T>()`           | partial record      | `set`、`delete`、`replace`                   |
+| 有序标量/结构条目    | `list({ keyOf })`          | array               | `insert`、`move`、`remove`、`replace`        |
+| 单根层级             | `tree<T>()`                | `{ rootId, nodes }` | `insert`、`move`、`remove`、`set`、`replace` |
+
+当顺序对产品可见时使用 table。不要用 map 加另一份 ids array 表示顺序：这会产生两套 mutation protocol 和两个顺序来源。list 只适合每个条目都有稳定、唯一应用 key 的情形；不能把当前 index 当作 `keyOf`。
+
+```ts
+import { field, list, map, object, schema, table, tree } from 'doxum';
+
+type Tag = { id: string; name: string };
+
+const note = object({ body: field<string>() });
+const documentSchema = schema({
+  notes: table(note),
+  tags: list<Tag>({ keyOf: tag => tag.id }),
+  collaborators: map(object({ name: field<string>() })),
+  outline: tree<{ title: string }>(),
+});
+```
+
+## 本地领域命令：读取、校验、写入
+
+所有修改要么全部成功、要么全部失败时，将领域命令放进同一个 transaction。业务规则依赖当前状态时，先读取再产生 operation；阻断型业务规则调用 `tx.reject`。
+
+```ts
+function completeTask(id: string) {
+  return runtime.update(tx => {
+    const task = tx.read.tasks.get(id);
+    if (!task) {
+      tx.reject({
+        source: 'application',
+        code: 'task-not-found',
+        message: `Task '${id}' does not exist.`,
+        address: ['tasks', id],
+      });
+    }
+    if (task.completed.get()) return { changed: false };
+
+    tx.write.tasks.item(id).completed.set(true);
+    tx.report({
+      source: 'application',
+      code: 'task-completed',
+      message: 'Task marked complete.',
+      address: ['tasks', id],
+    });
+    return { changed: true };
+  });
+}
+```
+
+`tx.report` 不会拒绝 transaction，适合 warning、审计反馈或伴随合法 commit 的应用消息。`tx.reject` 会中止 transaction，并让外层调用者得到 rejected result。两者都不能替代 malformed operation 的处理：引擎失败由 Doxum 提供的 `MutationIssue` 表示。
+
+## 在一个边界应用外部 operation
+
+将序列化、授权、网络排序和冲突策略集中在应用 adapter 中。adapter 判断一个 batch 可以应用后，再把完整 batch 交给 Doxum。
+
+```ts
+async function receiveRemote(batch: unknown) {
+  // 在这里执行认证、排序、去重和冲突策略。
+  const result = runtime.apply(batch, {
+    source: 'remote',
+    history: false,
+  });
+
+  if (result.status === 'rejected') {
+    logRejectedOperations(result.issues);
+    return;
+  }
+  if (result.status === 'committed') reportObserverErrors(result.observerErrors);
+}
+```
+
+上面的断言只应存在于真正接受未知运行时输入的动态边界；不要把 operation type 放宽到整个应用。Doxum 仍会在发布 commit 前校验 malformed envelope 与语义错误。
+
+`replace` 只用于新的、可信的 canonical snapshot。它会产生 reset impact 并使 local history 失效，不是表达微小变更的便捷写法。
+
+## 用 Anchor 放置有序条目
+
+table 与 list 共用同一套 `DocumentAnchor` 词汇：
+
+```ts
+{
+  at: 'start';
+}
+{
+  at: 'end';
+}
+{
+  before: 'other-id';
+}
+{
+  after: 'other-id';
+}
+```
+
+不要在应用代码中计算 index，而应使用 anchor。它表达领域位置，让 Doxum 校验缺失的引用，并让 table、list 与 operation replay 语义保持一致。
+
+```ts
+runtime.update(tx => {
+  tx.write.tasks.create({ id: 'review', value: newTask }, { before: 'publish' });
+  tx.write.tags.insert({ id: 'urgent', name: 'Urgent' }, { at: 'start' });
+  tx.write.tags.move('urgent', { after: 'planning' });
+});
+```
+
+## 将 tree 视为一个整体不变量
+
+Doxum tree 要么为空，要么存在唯一且连通的 root。`nodes` 必须维护双向 parent/child 关系、无重复 child、全量可达与无环。root replace 会校验完整 snapshot；本地 writer 会以增量方式维持该不变量。
+
+```ts
+runtime.update(tx => {
+  tx.write.outline.insert('root', { title: 'Project' });
+  tx.write.outline.insert('plan', { title: 'Plan' }, 'root');
+  tx.write.outline.move('plan', 'root', 0);
+  tx.write.outline.set('plan', { title: 'Plan release' });
+});
+```
+
+只有在 tree 为空时，才能不传 `parentId` 创建 root。root 已存在后，每个新节点都必须有已存在的 parent。不要将非 root move 到 `undefined`，不要重新挂载 root，也不要在经过校验的 `tree.replace` 或 runtime `replace` snapshot 之外直接编辑 `{ rootId, nodes }`。
+
+## 通过领域 target select 与 subscribe
+
+从所属 schema 创建 selector 一次。这为 subscription 与 impact 解释建立稳定的公共契约。
+
+```ts
+const notes = documentSchema.collection(path => path.notes);
+const body = documentSchema.value(path => path.notes.item('a').body);
+
+const unsubscribe = runtime.subscribe([notes, body], commit => {
+  if (commit.impact.affects(body)) refreshTitleUI();
+
+  const change = commit.impact.collection(notes);
+  if (change.kind === 'incremental' && change.updated.has('a')) refreshRow('a');
+});
+```
+
+只有需要将两个 impact target 当作值比较时，使用 `target.same(left, right)`。应使用 `target.address`、`target.id`、`target.belongs` 与 `target.bucket`，不要在 framework adapter 或局部 helper 中复制它们的解释逻辑。
+
+## 用 CollectionView 构建映射行
+
+当一个 table 或 map 需要可复用 read model 时，使用 collection view。mapping callback 可以读取 entry 的类型化字段；`isEqual` 允许 view 在重新映射出的 row 语义不变时保留旧值。
+
+```ts
+const notes = documentSchema.collection(path => path.notes);
+
+const noteSummaries = createCollectionView({
+  runtime,
+  source: notes,
+  map: (id, note) => ({ id, preview: note.body.get().slice(0, 80) }),
+  isEqual: (left, right) => left.id === right.id && left.preview === right.preview,
+});
+
+const stop = noteSummaries.item('a').subscribe(() => rerenderRow('a'));
+const all = noteSummaries.all.current();
+```
+
+不要让调用方把变更推入 view。它会监听声明的 source 并从 runtime state 重新计算。`noteSummaries` 和 `stop` 应随所属 UI 或 service 一起 dispose。
+
+## 用 MaterializedView 构建聚合或索引
+
+当你拥有可以根据 commit 增量更新的 aggregate 时，使用 materialized view。`update` 期间通过传入的 `impact` 对象检查影响范围；这会记录真实依赖，使之后无关的 commit 可以跳过此次 update。
+
+```ts
+const notes = documentSchema.collection(path => path.notes);
+
+const noteCount = createMaterializedView(runtime, {
+  build: ({ read }) => ({
+    value: read.notes.ids().length,
+    update: ({ impact, read }) => {
+      const change = impact.collection(notes);
+      if (
+        change.kind === 'incremental' &&
+        change.added.size === 0 &&
+        change.removed.size === 0 &&
+        change.updated.size === 0 &&
+        !change.orderChanged
+      ) {
+        return { kind: 'unchanged' };
+      }
+      return {
+        kind: 'changed',
+        value: read.notes.ids().length,
+        change,
+      };
+    },
+  }),
+});
+```
+
+局部增量逻辑无法安全处理一个 commit 时，返回 `rebuild`。后创建的 view 可以在 `sources` 中声明更早创建的 view；Doxum 会按创建顺序处理该图，并在外部 listener 看到 commit 前将其 flush 完成。
+
+## 在 React 中绑定读模型
+
+直接读取 document 时使用 `useDocumentSelector`。它会跟踪每次 selector 执行中读取的 path 和 collection entry，包括动态依赖。
+
+```tsx
+function Note({ id }: { id: string }) {
+  const body = useDocumentSelector(runtime, read => read.notes.get(id)?.body.get());
+  return <p>{body ?? 'Missing note'}</p>;
+}
+```
+
+已有 read model 则使用更窄的 hook：
+
+```tsx
+function NoteRow({ id }: { id: string }) {
+  const summary = useReadable(noteSummaries.item(id));
+  return <p>{summary?.preview}</p>;
+}
+
+function UndoButton() {
+  const history = useHistory(runtime.history);
+  return (
+    <button disabled={history.undoDepth === 0} onClick={() => history.undo()}>
+      Undo
+    </button>
+  );
+}
+```
+
+selector 应保持纯粹：读取 Doxum state 并计算结果即可；不要在 selector 执行中写入、手动订阅或发起 I/O。
+
+## 测试真正发生变化的行为
+
+mutation 改动应覆盖成功 commit、部分 batch 的 rejected rollback、inverse/history 结果，以及相关 impact 或 subscription 行为。projection 改动应覆盖无关 commit、动态依赖、应当稳定的引用和 dispose。大型 table、list 与 tree 应增加回归测试，证明无关数据没有被复制或遍历。