doxum 0.1.10 → 0.1.11

package/README.md

@@ -234,6 +234,9 @@ Pure computations receive current values. Advanced processors use tagged specs:
 `project({ kind: 'collection', sources, build })`.
 Document collection events provide scoped `read.get/has/ids`, final candidate
 keys, order dirtiness, commits and reset state.
+Ordinary mappers intentionally model only one-source, same-key transforms.
+Cross-collection relationships use an advanced collection processor with explicit,
+application-owned dependency indexes; processor reads are not tracked automatically.
 
 Processors settle before external listeners. `store.batch` defers graph
 settlement and projection notifications, but document commits/listeners remain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",

package/skills/doxum-runtime/SKILL.md

@@ -7,6 +7,9 @@ description: 'Use doxum and doxum/react for schemas, scoped draft updates, Chang
 
 Read the [English guide](references/guide.en.md) or [中文指南](references/guide.zh-CN.md).
 For examples read [patterns](references/patterns.en.md) or [中文模式](references/patterns.zh-CN.md).
+For any projection design or implementation, especially custom processors or
+cross-collection dependencies, read the [projection reference](references/projections.en.md)
+or [中文 Projection 参考](references/projections.zh-CN.md).
 Before runtime changes read [invariants](references/invariants.en.md) or
 [中文不变量](references/invariants.zh-CN.md).
 
@@ -26,7 +29,11 @@ Before runtime changes read [invariants](references/invariants.en.md) or
   kinds, optional before/after order in the same group, and a separate root reset.
   Standalone order records and duplicate groups are invalid. Grouping preserves field-level impact.
 - Paths belong in subscription, impact and collection source callbacks.
-- Projection dependencies are explicit; React selectors track actual reads.
+- Projection definitions are lazy; one ProjectionStore owns each materialized graph.
+  Use ordinary mappers only for one-source, same-key transforms. Advanced processors
+  declare every source, own any forward/reverse dependency indexes, derive from final
+  batched source state, and rebuild on resets that invalidate those indexes. Core
+  projections never track reads automatically; React selectors do.
 - Observer errors leave commits accepted. Do not retry as if they rolled back.
 - Core stays framework-neutral; adapters use integration capabilities.
 - Local sync owns browser persistence/leadership. Network conflict policy and

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

@@ -91,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

@@ -79,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

@@ -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

@@ -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。