doxum 0.1.9 → 0.1.11

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

@@ -13,12 +13,12 @@ const document = createDocument({
   initial: { tasks: { a: { title: 'Write', done: false } } },
 });
 document.update(draft => {
-  const task = draft.tasks.a;
+  const task = draft.tasks.get('a');
   if (task) task.done = !task.done;
-  draft.tasks.b = { title: 'Review', done: false };
+  draft.tasks.put('b', { title: 'Review', done: false });
   return { warnings: [] };
 });
-const done = select(document, state => state.tasks.a?.done);
+const done = select(document, state => state.tasks.get('a')?.done);
 const tasks = select(document, state => snapshot(state.tasks));
 document.subscribe(
   path => path.tasks.item('a').done,
@@ -43,20 +43,24 @@ returns its original readonly reference. Published data is not frozen. Field cop
 are not supported; mutable exports and serialization belong to application boundaries.
 
 Infer preserves optional properties and flat variant unions. Read/Draft contain
-collection tools; assign(scope, key, inferValue) handles plain replacements containing
-nested table/list/tree data.
+collection tools. Maps use explicit methods; table/list/tree overload replace for
+member and whole-container replacement. `replace(parent, key, inferValue)` handles
+plain replacement of object or variant members that contain collection data.
 
 ## Containers And Validation
 
-| Definition                       | Data          | Draft methods                                                 |
-| -------------------------------- | ------------- | ------------------------------------------------------------- |
-| map(valueSchema, { key }?)       | record        | indexing, assignment, delete                                  |
-| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move                                |
-| list(field, { keyOf })           | array         | get/has/ids/insert/set/remove/move/replace                    |
-| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/set/remove/move/replace |
+| Definition                       | Data          | Draft methods                                             |
+| -------------------------------- | ------------- | --------------------------------------------------------- |
+| map(valueSchema, { key }?)       | record        | get/has/ids/put/remove/replace                            |
+| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move/replace                    |
+| list(field, { keyOf })           | array         | get/has/ids/insert/remove/move/replace                    |
+| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/remove/move/replace |
 
-Read scopes expose only read methods. Map supports field/object/variant values.
-List replacement retains the addressed key. Simple arrays and strokes can be one
+Read scopes expose only read methods. Map supports field/object/variant values;
+put is an upsert and removing a missing key is a no-op. `replace(id, value)` is
+existing-only for table/list/tree, preserves table/list order, and changes only a
+tree payload. `replace(value)` replaces a whole collection. List member replacement
+retains the addressed key. Simple arrays and strokes can be one
 atomic field. Optional supports field/variant/map/list/tree. Absent differs from
 present undefined. Variant tags are readonly; change branch by whole replacement.
 
@@ -64,7 +68,7 @@ Pure synchronous functions and Standard Schema v1 validators receive original in
 They must not mutate it; successful output is ignored, with no copy or deep conversion
 check. Transform values before entering Doxum. parse(model, unknown) copies validated
 structure and shares readonly payloads; strict parse requires atomic validators.
-Branded map/table keys flow through access, symbolic paths and impact.
+Branded map/table keys flow through methods, symbolic paths and impact.
 Path callbacks describe locations, including absent entries, and compile at registration.
 React useDocumentSelector tracks actual reads and changes dependencies when branching.
 
@@ -87,6 +91,11 @@ Use `project(document, path => path.tasks, mapper)` for incremental mapping.
 Pure values use `project(sources, compute)`; stateful algorithms use tagged value
 or collection specs. Definitions are lazy and are materialized by a
 `createProjectionStore({ onError })` instance. Sources remain explicit.
+Ordinary mappers only model one-source, same-key transforms. Cross-collection or
+cross-key dependencies use an advanced collection processor with an application-owned
+reverse dependency index; core does not track reads performed by processors. See the
+[projection reference](projections.en.md) for event shapes, lifecycle, writer semantics,
+join indexing, batching, and fault recovery.
 `input` and `project(readable)` connect external boundary values. Dispose the store
 with the owning service. `store.batch` defers projection settlement/listeners, not document commits/listeners. Reads
 inside a batch see the last publication; no cross-document rollback is provided.

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

@@ -13,12 +13,12 @@ const document = createDocument({
   initial: { tasks: { a: { title: 'Write', done: false } } },
 });
 document.update(draft => {
-  const task = draft.tasks.a;
+  const task = draft.tasks.get('a');
   if (task) task.done = !task.done;
-  draft.tasks.b = { title: 'Review', done: false };
+  draft.tasks.put('b', { title: 'Review', done: false });
   return { warnings: [] };
 });
-const done = select(document, state => state.tasks.a?.done);
+const done = select(document, state => state.tasks.get('a')?.done);
 const tasks = select(document, state => snapshot(state.tasks));
 document.subscribe(
   path => path.tasks.item('a').done,
@@ -37,25 +37,28 @@ object/variant 结构只接受 schema 声明的自身属性及 variant 判别字
 snapshot 只复制 schema 结构；snapshot(rawPayload) 返回原始只读引用。
 发布数据不做运行时冻结，不再支持字段 copier。需要可修改副本或序列化时由应用边界显式处理。
 
-Infer 保留 optional 属性和扁平 variant 联合。Read/Draft 带集合方法；
-含 table/list/tree 数据的整体替换使用 assign(scope, key, inferValue)。
+Infer 保留 optional 属性和扁平 variant 联合。Read/Draft 带集合方法。map 使用显式方法；
+table/list/tree 的 replace 同时支持成员和整体替换。含集合数据的 object/variant 成员
+使用 `replace(parent, key, inferValue)` 传入普通 Infer 数据。
 
 ## 容器与校验
 
-| 声明                             | 数据          | Draft 方法                                                    |
-| -------------------------------- | ------------- | ------------------------------------------------------------- |
-| map(valueSchema, { key }?)       | record        | 索引、赋值、delete                                            |
-| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move                                |
-| list(field, { keyOf })           | 普通数组      | get/has/ids/insert/set/remove/move/replace                    |
-| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/set/remove/move/replace |
+| 声明                             | 数据          | Draft 方法                                                |
+| -------------------------------- | ------------- | --------------------------------------------------------- |
+| map(valueSchema, { key }?)       | record        | get/has/ids/put/remove/replace                            |
+| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move/replace                    |
+| list(field, { keyOf })           | 普通数组      | get/has/ids/insert/remove/move/replace                    |
+| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/remove/move/replace |
 
-Read 只暴露读取方法。map 支持 field/object/variant。list 替换项必须保持寻址键。
+Read 只暴露读取方法。map 支持 field/object/variant；put 是 upsert，remove 缺失键是 no-op。
+table/list/tree 的 `replace(id, value)` 只替换已存在成员，保持 table/list 顺序，且 tree
+只改变 payload；`replace(value)` 替换整个集合。list 替换项必须保持寻址键。
 简单数组与笔画可作为一个原子 field。optional 支持 field/variant/map/list/tree，
 缺失与存在的 undefined 不同。variant tag 只读，通过整体替换切换分支。
 
 校验器是纯同步函数或 Standard Schema v1，直接接收原始引用且不得修改它。
 成功返回值被忽略，不复制输入，也不深度检查转换；数据转换在进入 Doxum 前完成。
-parse(model, unknown) 复制校验后的结构并共享只读 payload；严格解析要求原子字段具备校验器。品牌键贯穿 map/table 访问、
+parse(model, unknown) 复制校验后的结构并共享只读 payload；严格解析要求原子字段具备校验器。品牌键贯穿 map/table 方法、
 符号路径和 impact。路径回调描述地址，包括缺失键，订阅注册时解析。
 React useDocumentSelector 追踪实际读取，并在选择分支改变时更新依赖。
 
@@ -76,6 +79,10 @@ observerErrors 属于已提交结果。
 纯派生值使用 `project(sources, compute)`；有状态算法使用带 kind 的 value
 或 collection spec。定义是惰性的，由 `createProjectionStore({ onError })`
 实例物化和管理。sources 仍然显式声明。
+普通 mapper 只表达单 source、同键转换。跨集合或跨键依赖使用 advanced collection
+processor，并由应用维护反向依赖索引；core 不追踪 processor 内的读取。event 形状、
+生命周期、writer 语义、join 索引、batch 与 fault 恢复见
+[Projection 参考](projections.zh-CN.md)。
 `input` 与 `project(readable)` 接入外部边界值。随所属服务 dispose store。
 `store.batch` 推迟投影结算与通知，但不推迟文档提交和文档通知；内部读取上次发布值，
 不提供跨文档回滚。

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

@@ -11,7 +11,7 @@ const model = object({
 });
 ```
 
-Edit position.x, replace stroke whole, use rows.set(key, value) for keyed item edits.
+Edit position.x, replace stroke whole, and use rows.replace(key, value) for keyed item edits.
 
 ## Complex Replacement
 
@@ -21,13 +21,13 @@ const model = object({
 });
 const document = createDocument({ schema: model, initial: { entries: {} } });
 document.update(draft => {
-  assign(draft.entries, 'a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
-  draft.entries.a!.rows.get('x')!.title = 'Updated';
+  draft.entries.put('a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
+  draft.entries.get('a')!.rows.get('x')!.title = 'Updated';
 });
 ```
 
-TypeScript cannot express different read/write types for mapped properties.
-assign checks Infer replacement data and uses the same mutation session.
+Map entries use put. Use top-level replace for object/variant members whose Draft
+type contains collection tools; collection replace(next) handles whole containers.
 
 ## Domain Keys
 
@@ -45,7 +45,7 @@ const model = object({ people: map(object({ name: field(text) }), { key: personI
 const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-Brands flow through indexed access, table methods, symbolic paths and collection impact.
+Brands flow through map/table methods, symbolic paths and collection impact.
 
 ## Ordered Edits, History And Replay
 
@@ -101,4 +101,7 @@ Use `useProjection` with a store for projection definitions; use `useReadable`
 for history and other existing Readable values. Custom collection processors stage
 writer.set/remove/order/replace and use scoped previous/next reads. Candidates span
 the complete batch; derive output from final state. Processor dependencies remain
-explicit even though React selectors track actual reads.
+explicit even though React selectors track actual reads. Use a mapper only when a
+source key affects the same output key. For cross-collection joins, declare every
+source and maintain the domain's reverse dependency index as described in the
+[projection reference](projections.en.md).

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

@@ -11,7 +11,7 @@ const model = object({
 });
 ```
 
-position.x 细粒度赋值；stroke 整体替换；rows.set(key, value) 按稳定键替换项。
+position.x 细粒度赋值；stroke 整体替换；rows.replace(key, value) 按稳定键替换项。
 
 ## 含集合的整体替换
 
@@ -21,13 +21,13 @@ const model = object({
 });
 const document = createDocument({ schema: model, initial: { entries: {} } });
 document.update(draft => {
-  assign(draft.entries, 'a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
-  draft.entries.a!.rows.get('x')!.title = 'Updated';
+  draft.entries.put('a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
+  draft.entries.get('a')!.rows.get('x')!.title = 'Updated';
 });
 ```
 
-TypeScript 映射属性不能分别指定读写类型。assign 校验对应 Infer 数据，
-经同一 mutation session 修改。
+map 条目使用 put。Draft 类型含集合方法的 object/variant 成员使用顶层 replace；
+集合整体替换使用集合自身的 replace(next)，并经同一 mutation session 修改。
 
 ## 领域键
 
@@ -45,7 +45,7 @@ const model = object({ people: map(object({ name: field(text) }), { key: personI
 const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-品牌类型贯穿索引、table 方法、符号路径和 collection impact。
+品牌类型贯穿 map/table 方法、符号路径和 collection impact。
 
 ## 顺序、History 与重放
 
@@ -100,4 +100,6 @@ store.get(scaled);
 使用 `useReadable` 或 `useHistory`。自定义集合 processor 通过
 writer.set/remove/order/replace 暂存输出，
 previous/next 读取只在作用域内有效。candidates 汇总整个 batch，以最终状态派生输出。
-React 追踪实际读取，但 processor 依赖仍显式声明。
+React 追踪实际读取，但 processor 依赖仍显式声明。只有 source 键影响同名输出键时
+才使用 mapper。跨集合 join 应声明全部 source，并按
+[Projection 参考](projections.zh-CN.md)维护领域反向依赖索引。

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

@@ -0,0 +1,211 @@
+# Doxum Projection Reference
+
+Use this reference when choosing, implementing, or reviewing a projection. The
+[public long-form contract](../../../docs/projections.md) provides a complete join
+example; source code inspection should not be necessary for normal application work.
+
+## Choose The Form
+
+| Relationship                                  | API                                               |
+| --------------------------------------------- | ------------------------------------------------- |
+| Whole document source                         | `project(document)`                               |
+| Target-limited document source                | `project(document, [pick, ...])`                  |
+| Document collection source                    | `project(document, pick)`                         |
+| One source key to the same output key         | `project(collection, mapper)`                     |
+| Pure current values to one value              | `project(sources, compute)`                       |
+| Stateful incremental value                    | `project({ kind: 'value', sources, build })`      |
+| Multiple sources or cross-key collection work | `project({ kind: 'collection', sources, build })` |
+| Application input                             | `input(initial)` and `store.set(input, value)`    |
+| Existing `Readable`                           | `project(readable)`                               |
+
+Definitions are lazy and reusable. `createProjectionStore({ onError })` owns one
+materialization graph. Every store has independent published values, revisions,
+inputs, subscriptions, processor instances, and closure indexes.
+
+An ordinary mapper is deliberately limited to:
+
+```text
+source key K changed -> output key K may change
+```
+
+It rebuilds on reset and follows source order, but does not track reads performed
+inside the mapper. Never read another collection in a mapper and assume it becomes
+a dependency. Declare all sources in an advanced processor instead.
+
+## Source Event Contract
+
+Advanced processors receive events, not just current values:
+
+```ts
+type ValueEvent<T> = {
+  value: T;
+  previous: T;
+  changed: boolean;
+  revision: number;
+  reset: boolean;
+};
+
+type CollectionEvent<K extends string, V> = {
+  get(key: K): V | undefined;
+  has(key: K): boolean;
+  ids(): readonly K[];
+  change: CollectionImpact<K> | undefined;
+  revision: number;
+  reset: boolean;
+};
+
+type DocumentEvent<S> = {
+  read: Read<S>;
+  revision: number;
+  commits: readonly DocumentCommit<S>[];
+  reset: boolean;
+};
+
+type DocumentCollectionEvent<S, N, K extends string> = {
+  read: CollectionAccess<K, N>;
+  revision: number;
+  commits: readonly DocumentCommit<S>[];
+  reset: boolean;
+  candidates: { keys: readonly K[]; orderDirty: boolean };
+};
+```
+
+Projected collection `change` is incremental (`added`, `removed`, `updated`,
+`orderChanged`), reset, or undefined. Document collection candidates are the
+union across all relevant commits in a store batch. A later commit may cancel an
+earlier one without removing its candidate key. Always derive from final `read`
+state. Use `commit.impact.collection(pick)` for per-commit relationship changes.
+
+Across a batch, a value event's `previous` is the pre-batch value and `value` is
+the final value. A net-zero document transaction produces no commit or candidates.
+
+## Advanced Value Processor
+
+```ts
+const value = project({
+  kind: 'value',
+  sources,
+  build: events => ({
+    value: buildValue(events),
+    update: events =>
+      needsRebuild(events)
+        ? { kind: 'rebuild' }
+        : changed(events)
+          ? { kind: 'changed', value: updateValue(events) }
+          : { kind: 'unchanged' },
+  }),
+});
+```
+
+Prefer `project(sources, compute)` unless retained state prevents meaningful work.
+
+## Advanced Collection Processor
+
+```ts
+const result = project({
+  kind: 'collection',
+  sources,
+  name: 'optional diagnostic name',
+  isEqual: Object.is,
+  build: ({ sources, previous, next, writer }) => {
+    // Build the complete output and any store-local indexes.
+    return {
+      update: ({ sources, previous, next, writer }) => {
+        // Stage only affected keys, or return { kind: 'rebuild' }.
+      },
+    };
+  },
+});
+```
+
+`build` runs on first materialization, source reset, explicit `store.rebuild`, an
+update-requested rebuild, and fault recovery. Build starts from a cleared output
+and must stage the complete result. Its closure state is local to one store and
+must be reconstructible from sources.
+
+`update` runs when a declared source participates in settlement. Returning
+`{ kind: 'rebuild' }` discards staged update writes and performs a fresh build.
+All callbacks are synchronous; Promises and thenables are rejected. Reads and
+writes during processing or notification must not reenter a source or document.
+
+`previous`, `next`, source readers, and `writer` are borrowed for the current
+synchronous callback only:
+
+- `previous` sees only published output.
+- `next` immediately sees current staged writes.
+- `writer.set(key, value)` stages presence.
+- `writer.remove(key)` stages absence; a missing removal is a no-op.
+- Repeated operations on one key use the last operation.
+- `writer.order(ids)` supplies the entire next order, with every key exactly once.
+- `writer.replace(entries)` clears and replaces all output in entry order; keys
+  must be unique.
+
+Staged output publishes atomically. Equality defaults to `Object.is`; equal sets
+keep the old reference. Net-zero output does not increment revision or notify.
+
+## Cross-Collection Join Pattern
+
+Do not add a generic join abstraction. The domain owns missing references,
+cardinality, reconnect, delete, ordering, and result-key policy. Model the join as
+an advanced collection with explicit sources and indexes.
+
+For routes derived from `edges(from, to)` and node geometry, maintain:
+
+```text
+endpoints: edgeId -> [fromNodeId, toNodeId]
+adjacency: nodeId -> Set<edgeId>
+```
+
+On build, scan edges once, populate both indexes, and write the complete routes.
+On an edge event:
+
+1. Read exact changed edge ids from each commit's collection impact.
+2. Detach every changed id from its old endpoints.
+3. Read final edge state; attach its final endpoints, or delete its forward entry.
+4. Add that edge id to the affected output set.
+
+On a node collection event, map added/updated/removed node ids through `adjacency`
+and add only adjacent edges to the affected set. Finally read current endpoint
+geometry and set or remove each affected route. Rebuild on either source reset.
+
+After an edge reconnects, the old node must no longer select it. Deleting an edge
+must remove both forward and reverse entries. Missing endpoint behavior is an
+explicit domain decision. Do not scan all edges for every node change unless the
+known collection size makes that tradeoff intentional.
+
+Closure indexes are not part of the writer's staged transaction. An uncaught
+processor failure triggers fresh-build recovery, but a processor that catches a
+failure and continues keeps its own mutations. Perform fallible work before
+mutating live indexes, stage temporary index changes and commit them on success,
+or request a complete rebuild.
+
+## Batching, Faults, And Lifetime
+
+`store.batch` defers projection settlement and projection listeners only. Document
+commits and document listeners remain synchronous. Reads inside the batch return
+the last publication; settlement after the outer batch uses final source state.
+There is no cross-document rollback.
+
+Processor or writer validation failure publishes no partial output. The runtime
+may retry with a fresh build; persistent failure faults that projection and blocks
+its descendants while independent branches continue. Reads then throw
+`ProjectionError`. A later source update or `store.rebuild(projection)` can recover.
+`onError` also receives source, blocked, and listener failures. Listener failures
+never undo published projection state or accepted document commits.
+
+`store.release(projection)` releases an independently releasable materialization;
+do not release a node still used by a materialized downstream projection.
+`store.dispose()` invalidates the complete graph and releases its subscriptions.
+
+## Review Checklist
+
+- All result-changing sources are declared.
+- Candidate selection covers add, update, remove, reconnect, and missing reference.
+- Batch logic reads final state instead of replaying imagined intermediate states.
+- Reset and explicit rebuild reconstruct complete output, order, and indexes.
+- Build never depends on prior output or a previous processor closure.
+- `writer.order` is complete and valid whenever used.
+- Equal values preserve references; unrelated changes produce no output revision.
+- A thrown update cannot silently corrupt closure indexes.
+- Tests cover unrelated commits, dynamic dependencies, stable references, reset,
+  batch behavior, recovery, and disposal.

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

@@ -0,0 +1,195 @@
+# Doxum Projection 参考
+
+设计、实现或审查 projection 时使用本文。[公开完整契约](../../../docs/projections.md)
+提供完整 join 示例；正常应用开发不应再要求阅读运行时源码。
+
+## 选择定义形式
+
+| 依赖关系                       | API                                               |
+| ------------------------------ | ------------------------------------------------- |
+| 整个文档作为 source            | `project(document)`                               |
+| 只关注指定文档路径             | `project(document, [pick, ...])`                  |
+| 一个文档集合 source            | `project(document, pick)`                         |
+| 一个 source 键映射到同名输出键 | `project(collection, mapper)`                     |
+| 当前 source 值纯计算出一个值   | `project(sources, compute)`                       |
+| 有状态增量 value               | `project({ kind: 'value', sources, build })`      |
+| 多 source 或跨键集合计算       | `project({ kind: 'collection', sources, build })` |
+| 应用输入                       | `input(initial)` 与 `store.set(input, value)`     |
+| 既有 `Readable`                | `project(readable)`                               |
+
+定义是惰性、可复用的描述。`createProjectionStore({ onError })` 拥有一个物化图。
+同一定义在不同 store 内分别拥有发布值、revision、input、订阅、processor 实例和闭包索引。
+
+普通 mapper 的契约有意限制为：
+
+```text
+source 键 K 变化 -> 输出键 K 可能变化
+```
+
+它在 reset 时重建并跟随 source 顺序，但不会追踪 mapper 内的读取。不要在 mapper
+里读取另一个集合并假定它自动成为依赖；应改用 advanced processor，并显式声明所有 source。
+
+## Source Event 契约
+
+advanced processor 接收 event，而不只是当前值：
+
+```ts
+type ValueEvent<T> = {
+  value: T;
+  previous: T;
+  changed: boolean;
+  revision: number;
+  reset: boolean;
+};
+
+type CollectionEvent<K extends string, V> = {
+  get(key: K): V | undefined;
+  has(key: K): boolean;
+  ids(): readonly K[];
+  change: CollectionImpact<K> | undefined;
+  revision: number;
+  reset: boolean;
+};
+
+type DocumentEvent<S> = {
+  read: Read<S>;
+  revision: number;
+  commits: readonly DocumentCommit<S>[];
+  reset: boolean;
+};
+
+type DocumentCollectionEvent<S, N, K extends string> = {
+  read: CollectionAccess<K, N>;
+  revision: number;
+  commits: readonly DocumentCommit<S>[];
+  reset: boolean;
+  candidates: { keys: readonly K[]; orderDirty: boolean };
+};
+```
+
+投影集合的 `change` 可能是 incremental（`added`、`removed`、`updated`、
+`orderChanged`）、reset 或 undefined。文档集合的 candidates 是一个 store batch
+内所有相关 commit 的并集。后续 commit 即使抵消早先变化，也不会移除候选键。
+必须用最终 `read` 状态计算输出。需要维护关系索引时，用
+`commit.impact.collection(pick)` 取得每次 commit 的精确变化。
+
+batch 中 value event 的 `previous` 是 batch 前的值，`value` 是最终值。
+单个净零文档事务不会产生 commit 或 candidates。
+
+## Advanced Value Processor
+
+```ts
+const value = project({
+  kind: 'value',
+  sources,
+  build: events => ({
+    value: buildValue(events),
+    update: events =>
+      needsRebuild(events)
+        ? { kind: 'rebuild' }
+        : changed(events)
+          ? { kind: 'changed', value: updateValue(events) }
+          : { kind: 'unchanged' },
+  }),
+});
+```
+
+除非保留状态能避免有意义的工作，否则优先使用 `project(sources, compute)`。
+
+## Advanced Collection Processor
+
+```ts
+const result = project({
+  kind: 'collection',
+  sources,
+  name: 'optional diagnostic name',
+  isEqual: Object.is,
+  build: ({ sources, previous, next, writer }) => {
+    // 构建完整输出和 store 局部索引。
+    return {
+      update: ({ sources, previous, next, writer }) => {
+        // 只暂存受影响的键，或返回 { kind: 'rebuild' }。
+      },
+    };
+  },
+});
+```
+
+首次物化、source reset、显式 `store.rebuild`、update 请求 rebuild 以及 fault
+恢复时会调用 `build`。build 从已清空的输出开始，必须写出完整结果。
+其闭包状态只属于一个 store，并且必须能完全由 sources 重建。
+
+任一已声明 source 参与结算时调用 `update`。返回 `{ kind: 'rebuild' }` 会丢弃
+本次 update 暂存的写入，并执行全新 build。所有回调同步执行；Promise 和 thenable
+会被拒绝。processing 或 notification 中的读取和写入不得重入 source 或 document。
+
+`previous`、`next`、source reader 和 `writer` 都只在当前同步回调内有效：
+
+- `previous` 只看到已发布输出。
+- `next` 立即看到当前暂存的写入。
+- `writer.set(key, value)` 暂存存在值。
+- `writer.remove(key)` 暂存缺失；删除不存在的键是 no-op。
+- 同一键多次操作以最后一次为准。
+- `writer.order(ids)` 提供完整 next 顺序，每个输出键必须恰好出现一次。
+- `writer.replace(entries)` 清空并按 entries 顺序替换全部输出，键不能重复。
+
+暂存输出原子发布。相等判断默认使用 `Object.is`，相等的 set 保留旧引用。
+净零输出不增加 revision，也不通知 listener。
+
+## 跨集合 Join 模式
+
+不要增加通用 join 抽象。缺失引用、基数、重连、删除、顺序和结果键策略都属于领域逻辑。
+应使用带显式 sources 和索引的 advanced collection 表达 join。
+
+例如 route 由 `edges(from, to)` 和 node 几何信息计算，维护：
+
+```text
+endpoints: edgeId -> [fromNodeId, toNodeId]
+adjacency: nodeId -> Set<edgeId>
+```
+
+build 时扫描一次 edges，填充两个索引并写出全部 routes。edge 变化时：
+
+1. 从每个 commit 的 collection impact 读取精确变化的 edge id。
+2. 将每个变化 id 从旧 endpoints 中解绑。
+3. 读取最终 edge 状态；绑定其最终 endpoints，或删除其正向索引。
+4. 将该 edge id 加入受影响输出集合。
+
+node 集合变化时，把 added/updated/removed node id 通过 `adjacency` 映射为相邻
+edge，并只将这些 edge 加入受影响集合。最后读取当前 endpoint 几何信息，对每个
+受影响 route 执行 set 或 remove。任一 source reset 都应 rebuild。
+
+edge 重连后，旧 node 不得再选中它；删除 edge 必须同时移除正向和反向索引。
+endpoint 缺失时的行为由领域显式定义。除非集合规模已知且权衡明确，不要在每次
+node 变化时扫描全部 edges。
+
+闭包索引不属于 writer 的 staged transaction。未捕获的 processor 失败会触发 fresh
+build 恢复，但 processor 如果自行捕获失败后继续执行，其索引修改会保留。先完成可能
+失败的工作再修改活动索引，或在临时状态上暂存索引变化并在成功后提交，或请求完整 rebuild。
+
+## Batch、Fault 与生命周期
+
+`store.batch` 只推迟 projection 结算和 projection listener；文档 commit 和文档
+listener 仍同步执行。batch 内读取返回上次发布值，最外层 batch 结束后根据最终
+source 状态结算。不提供跨文档回滚。
+
+processor 或 writer 校验失败不会发布部分输出。runtime 可以用新 build 重试；
+持续失败会使该 projection fault，并阻塞下游，独立分支仍继续工作。此时读取抛
+`ProjectionError`。后续 source 更新或 `store.rebuild(projection)` 可以恢复。
+`onError` 还接收 source、blocked 和 listener 失败。listener 失败不会撤销已发布
+projection 状态或已接受的文档 commit。
+
+`store.release(projection)` 释放可独立释放的物化结果；仍被已物化下游使用的节点
+不能释放。`store.dispose()` 使整个图失效并解除其全部订阅。
+
+## 审查清单
+
+- 所有能改变结果的 source 都已声明。
+- 候选选择覆盖 add、update、remove、reconnect 和缺失引用。
+- batch 逻辑读取最终状态，而不是模拟中间状态。
+- reset 和显式 rebuild 能重建完整输出、顺序和索引。
+- build 不依赖旧输出或旧 processor 闭包。
+- 使用 `writer.order` 时提供完整且有效的顺序。
+- 相等结果保留引用；无关变化不产生输出 revision。
+- update 抛错不会悄悄破坏闭包索引。
+- 测试覆盖无关 commit、动态依赖、稳定引用、reset、batch、恢复和 disposal。