doxum 0.1.4 → 0.1.6

package/package.json

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

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

@@ -24,8 +24,8 @@ resolution.
 | Replace an entire trusted snapshot    | `runtime.replace(document, options)`                     |
 | Observe one schema location           | `schema.value` plus `runtime.subscribe`                  |
 | Observe a table or map                | `schema.collection` plus `runtime.subscribe`             |
-| Maintain mapped collection data       | `createCollectionView`                                   |
-| Maintain an aggregate or index        | `createMaterializedView`                                 |
+| Maintain mapped collection data       | `projection.map`                                         |
+| Maintain an aggregate or index        | `projection.value / projection.collection`               |
 | Read in React                         | `useDocumentSelector`, `useReadable`, or `useReadable`   |
 
 Do not write a second mutable copy of the document. `createDocument` is the
@@ -163,6 +163,11 @@ the same API except `move`, because it is unordered. Lists offer `insert`,
 specified in the schema. See [patterns.en.md](patterns.en.md) for complete
 collection and tree examples.
 
+Optional field, variant, dict, list, and tree writers expose `clear()`. Optional
+structured leaves can also be initialized from an absent state with `replace()`.
+Optional objects, tables, and maps have no whole-value clear; modify them through
+their child writers or collection operations.
+
 ## Replay operations at the boundary
 
 Use `apply` for operation batches that came from persistence, a network
@@ -288,26 +293,38 @@ comparison helpers in application modules.
 
 ## Build derived read models
 
-`createCollectionView` maps one table or map into stable ids, cached `item(id)`
-readables, and a lazy `all` array. It updates only affected entries where possible.
-
 ```ts
-import { createCollectionView } from 'doxum';
-
-const taskTitles = createCollectionView({
-  runtime,
-  source: taskSchema.collection(path => path.tasks),
-  map: (_id, task) => task.title.get(),
+const projection = createProjectionRuntime({ onError: error => console.error(error) });
+const document = projection.document(runtime);
+const notes = document.collection(path => path.notes);
+const noteSummaries = projection.map(
+  notes,
+  (id, note) => ({ id, preview: note.body.get().slice(0, 80) }),
+  { isEqual: (a, b) => a.id === b.id && a.preview === b.preview }
+);
+const noteCount = projection.value({
+  sources: { notes },
+  build: ({ notes }) => ({
+    value: notes.read.ids().length,
+    update: ({ notes }) => ({
+      kind: 'changed',
+      value: notes.read.ids().length,
+    }),
+  }),
 });
-
-taskTitles.item('write-guide').current();
-taskTitles.all.current();
 ```
 
-Use `createMaterializedView` for an index or aggregate with custom incremental
-logic. A materialized view is derived state, not a caller-maintained cache. It
-may depend only on materialized views created earlier from the same runtime.
-Dispose every view when its owning feature is disposed.
+projection.map produces stable ids/item readables and lazy all. Declare a
+DocumentCollectionSource directly in any processor's sources, or use
+projection.value and projection.collection for explicit incremental logic.
+There is no automatic keyed dependency tracking. All sources belong to the
+same projection owner, but may refer to different document runtimes.
+
+Use projection.input(initial, { isEqual }) for boundary values; give processors
+its source and keep set at the application boundary. fromReadable attaches an
+existing external source without taking ownership of it. Batch synchronous
+multi-source changes before the first commit. Dispose the projection at service
+shutdown; React unmount only unsubscribes. Disposed handles throw.
 
 ## React integration
 

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

@@ -17,8 +17,8 @@
 | 整体替换可信快照           | `runtime.replace(document, options)`                  |
 | 监听一个 schema 位置       | `schema.value` + `runtime.subscribe`                  |
 | 监听 table 或 map          | `schema.collection` + `runtime.subscribe`             |
-| 维护映射后的集合数据       | `createCollectionView`                                |
-| 维护聚合或索引             | `createMaterializedView`                              |
+| 维护映射后的集合数据       | `projection.map`                                      |
+| 维护聚合或索引             | `projection.value / projection.collection`            |
 | 在 React 中读取            | `useDocumentSelector`、`useReadable` 或 `useReadable` |
 
 不要再维护一份可写的文档副本。`createDocument` 是 canonical state 的唯一所有者。
@@ -135,6 +135,10 @@ runtime.update(tx => {
 
 table 支持 `create`、`item`、`remove` 和 `move`。map 与之相同，但没有 `move`，因为它无顺序。list 支持 `insert`、`move`、`remove` 与 `replace`；其身份来自 schema 中的 `keyOf`。完整的集合与 tree 模式见 [patterns.zh-CN.md](patterns.zh-CN.md)。
 
+optional 的 field、variant、dict、list 和 tree writer 提供 `clear()`；其中结构化叶子也可
+在当前缺失时直接调用 `replace()` 建立值。optional object、table 和 map 没有整体 clear，
+应通过子 writer 或集合操作修改。
+
 ## 在边界回放 operation
 
 来自持久化、网络适配器或其他外部边界的 operation batch 应通过 `apply` 回放。Doxum 会在 mutation code 看到数据前解码未知 operation payload，按 schema 解析每个地址，并原子地执行整个 batch。
@@ -239,22 +243,30 @@ value selector 使用 `commit.impact.affects(target)`；table 或 map selector
 
 ## 构建派生读模型
 
-`createCollectionView` 将一个 table 或 map 映射为稳定的 ids、缓存的 `item(id)` readable 和惰性 `all` 数组；在可能的情况下只更新受影响的条目。
-
 ```ts
-import { createCollectionView } from 'doxum';
-
-const taskTitles = createCollectionView({
-  runtime,
-  source: taskSchema.collection(path => path.tasks),
-  map: (_id, task) => task.title.get(),
+const projection = createProjectionRuntime({ onError: error => console.error(error) });
+const document = projection.document(runtime);
+const notes = document.collection(path => path.notes);
+const noteSummaries = projection.map(
+  notes,
+  (id, note) => ({ id, preview: note.body.get().slice(0, 80) }),
+  { isEqual: (a, b) => a.id === b.id && a.preview === b.preview }
+);
+const noteCount = projection.value({
+  sources: { notes },
+  build: ({ notes }) => ({
+    value: notes.read.ids().length,
+    update: ({ notes }) => ({
+      kind: 'changed',
+      value: notes.read.ids().length,
+    }),
+  }),
 });
-
-taskTitles.item('write-guide').current();
-taskTitles.all.current();
 ```
 
-需要自定义增量逻辑的索引或聚合使用 `createMaterializedView`。materialized view 是派生状态，不是由调用方手工同步的 cache；它只能依赖同一 runtime 中更早创建的 materialized view。每个 view 都要由所属功能在销毁时释放。
+projection.map 提供稳定的 ids/item readable 和惰性 all。DocumentCollectionSource 可直接用于自定义 processor 的 sources；projection.value 和 projection.collection 承载显式增量计算。不自动跟踪 keyed 依赖。sources 属于同一 projection owner，但可接入不同 document runtime。
+
+projection.input(initial, { isEqual }) 用于边界值；应用保留 set，processor 只接收 source。fromReadable 接入已有外部 source，不取得其生命周期所有权。多 source 同步更新应在首次 commit 前进入 batch。projection 随 service 销毁，React unmount 只取消订阅，disposed handle 明确抛错。
 
 ## React 集成
 

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

@@ -117,15 +117,18 @@ and history stay settled.
 
 ## Derived state is declared, not synchronized by callers
 
-`CollectionView` derives one declared collection and incrementally maintains
-ids, keyed values, and a lazy aggregate array. `MaterializedView` derives one
-value from document reads, tracked impact dependencies, and optional earlier
-materialized sources. A materialized view can only depend on views of the same
-runtime that were created before it.
-
-Do not cache derived values inside canonical document state unless they are
-real domain data. Do not have UI code manually feed changes into a view. Dispose
-views and subscriptions with their owner.
+ProjectionCollection and ProjectionValue share one explicit source graph and
+publication mechanism. Only scoped processors write derived output. Application
+code selects candidate keys from native impacts; Doxum owns final change,
+equality, revision and notification. Never expose mutable private indexes or
+retain scoped readers/writers. Updates must be synchronous.
+
+All affected nodes settle before listeners; failures discard staged output and
+attempt one fresh build before faulting. Faulted ancestors block descendants.
+Listener exceptions are isolated. Source writes are forbidden during graph
+processing and notification. Explicit batch defers graph publication, not
+canonical commits or document listeners, and never promises source rollback.
+Dispose the owner; do not dispose a node while it still has consumers.
 
 ## Framework and product boundaries
 

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

@@ -78,9 +78,9 @@ update 与 notification 窗口中禁止写入。processor、flush 和 listener e
 
 ## 派生状态应声明，而不是由调用方同步
 
-`CollectionView` 从一个已声明的 collection 派生，并增量维护 ids、keyed values 和惰性 aggregate array。`MaterializedView` 从 document read、跟踪到的 impact dependency 和可选的更早 materialized source 派生一个值。materialized view 只能依赖同一 runtime 中比它更早创建的 view。
+ProjectionCollection 和 ProjectionValue 共用显式 source 图与发布机制。只有 scoped processor 写入派生输出。应用根据原生 impact 选择候选 key，Doxum 拥有最终 change、equality、revision 和 notification。不能泄漏可变私有索引，也不能保留 scoped reader/writer。update 必须同步。
 
-不要把 derived value 缓存在 canonical document state 中，除非它本来就是领域数据。不要让 UI 手工将变更推入 view。view 与 subscription 都应随 owner dispose。
+受影响节点全部 settle 后再通知。失败丢弃候选输出，限一次全新 build 恢复，持续失败阻断下游；listener 错误逐个隔离。处理和通知期间禁止 source write。显式 batch 延迟派生图发布，不延迟 canonical commit 或 document listener，不承诺 source rollback。owner 负责 dispose，仍有消费者的节点不能单独释放。
 
 ## Framework 与产品边界
 

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

@@ -24,6 +24,13 @@ 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`.
 
+Entry readers and writers for tables and maps are derived directly from the entry
+schema node. Structured entries retain their specialized tree, list, dict, or
+variant access instead of being reconstructed from runtime values into a broad
+object union. Optional fields and optional variant, dict, list, and tree leaves
+also expose `clear()` and can be initialized from an absent state with
+`replace()`; objects, tables, and maps keep their child or collection operations.
+
 ```ts
 import { field, list, map, object, schema, table, tree } from 'doxum';
 
@@ -181,68 +188,41 @@ 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.
+## Build explicit projections
 
 ```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,
-      };
-    },
+const projection = createProjectionRuntime({ onError: error => console.error(error) });
+const document = projection.document(runtime);
+const notes = document.collection(path => path.notes);
+const noteSummaries = projection.map(
+  notes,
+  (id, note) => ({ id, preview: note.body.get().slice(0, 80) }),
+  { isEqual: (a, b) => a.id === b.id && a.preview === b.preview }
+);
+const noteCount = projection.value({
+  sources: { notes },
+  build: ({ notes }) => ({
+    value: notes.read.ids().length,
+    update: ({ notes }) => ({
+      kind: 'changed',
+      value: notes.read.ids().length,
+    }),
   }),
 });
 ```
 
-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.
+Use map for one-to-one collection transforms. For custom indexes, use
+projection.collection with declared sources and scoped writer.set/remove/order/replace.
+Its previous and next readers separate published values from staged writes.
+Inspect each document source commit.impact, or an upstream collection change,
+to determine candidate keys. Dependencies are explicit and fixed, not learned
+from reads. Doxum determines final changes through equality.
+
+A failed update discards its instance and attempts one fresh build. Persistent
+faults block descendants; independent branches continue. Call rebuild through
+the node API, never manually emit. Dispose the projection with its owner.
+Wrap document mutation and editor cleanup in projection.batch before the first
+commit; reads inside the batch remain at the last published projection.
 
 ## Bind read models in React
 

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

@@ -19,6 +19,12 @@
 
 当顺序对产品可见时使用 table。不要用 map 加另一份 ids array 表示顺序：这会产生两套 mutation protocol 和两个顺序来源。list 只适合每个条目都有稳定、唯一应用 key 的情形；不能把当前 index 当作 `keyOf`。
 
+table/map 的 entry reader 与 writer 直接由 entry schema node 推导。结构化 entry 会保留
+自己的 tree、list、dict、variant 等专用 access，而不会从运行时 value 反推成普通对象或
+产生 value union。optional field 以及 optional 的 variant、dict、list、tree 结构叶子额外
+提供 `clear()`，并可在缺失状态通过 `replace()` 初始化；object、table、map 仍使用各自的
+子 writer 或集合操作。
+
 ```ts
 import { field, list, map, object, schema, table, tree } from 'doxum';
 
@@ -151,58 +157,34 @@ const unsubscribe = runtime.subscribe([notes, body], commit => {
 
 只有需要将两个 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 projection = createProjectionRuntime({ onError: error => console.error(error) });
+const document = projection.document(runtime);
+const notes = document.collection(path => path.notes);
+const noteSummaries = projection.map(
+  notes,
+  (id, note) => ({ id, preview: note.body.get().slice(0, 80) }),
+  { isEqual: (a, b) => a.id === b.id && a.preview === b.preview }
+);
+const noteCount = projection.value({
+  sources: { notes },
+  build: ({ notes }) => ({
+    value: notes.read.ids().length,
+    update: ({ notes }) => ({
+      kind: 'changed',
+      value: notes.read.ids().length,
+    }),
+  }),
 });
-
-const stop = noteSummaries.item('a').subscribe(() => rerenderRow('a'));
-const all = noteSummaries.all.current();
 ```
 
-不要让调用方把变更推入 view。它会监听声明的 source 并从 runtime state 重新计算。`noteSummaries` 和 `stop` 应随所属 UI 或 service 一起 dispose。
-
-## 用 MaterializedView 构建聚合或索引
+map 用于保留 key 和顺序的一对一映射。自定义索引使用 projection.collection，声明 sources，并通过 scoped writer.set/remove/order/replace 更新。previous 与 next 分别读取上次输出和本轮暂存结果。
 
-当你拥有可以根据 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,
-      };
-    },
-  }),
-});
-```
+根据每个 document source 的 commits 中的 impact，或上游 collection change，决定候选 key。依赖显式固定，不通过 reader 自动学习。Doxum 根据 equality 决定最终 change。
 
-局部增量逻辑无法安全处理一个 commit 时，返回 `rebuild`。后创建的 view 可以在 `sources` 中声明更早创建的 view；Doxum 会按创建顺序处理该图，并在外部 listener 看到 commit 前将其 flush 完成。
+update 失败后丢弃实例并限一次全新 build 恢复；持续失败阻断下游，独立分支继续。rebuild 经过同一调度图，不手动 emit。projection 随 owner dispose。使用 projection.batch 包住首次 document commit 之前到 editor cleanup 结束的完整同步动作；batch 内派生读取保持上次发布状态。
 
 ## 在 React 中绑定读模型