doxum 0.1.23 → 0.1.26

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

@@ -1,5 +1,8 @@
 # Doxum 使用指南
 
+`doxum`、`doxum/advanced`、`doxum/react`、`doxum/local-sync` 的精确公开签名见
+[API 参考](api.zh-CN.md)。本指南只保留选择原则与生命周期语义。
+
 ## 定义、修改与读取
 
 ```ts
@@ -16,7 +19,6 @@ document.update(draft => {
   const task = draft.tasks.get('a');
   if (task) task.done = !task.done;
   draft.tasks.put('b', { title: 'Review', done: false });
-  return { warnings: [] };
 });
 const done = read(document, state => state.tasks.get('a')?.done);
 const tasks = read(document, state => snapshot(state.tasks));
@@ -62,8 +64,9 @@ tree 可以为空。`tree(field(...))` 要求每个已存在节点都拥有自
 `tree(optional(field(...)))` 才允许节点缺失 payload，而 `optional(tree(...))` 独立控制整棵
 tree 成员是否可以缺失。
 
-校验器是纯同步函数或 Standard Schema v1，直接接收原始引用且不得修改它。
-成功返回值被忽略，不复制输入，也不深度检查转换；数据转换在进入 Doxum 前完成。
+函数 validator 是同步 predicate/assertion：返回 `true` 或 `undefined` 成功，
+返回 `false` 拒绝，assertion 也可以 throw。Standard Schema v1 成功时必须按 identity
+返回原输入；transform output 会被拒绝。validator 不得修改输入。数据转换在进入 Doxum 前完成。
 parse(model, unknown) 复制校验后的结构并共享只读 payload；严格解析要求原子字段具备校验器。品牌键贯穿 map/table 方法、
 符号路径和 impact。路径回调描述地址，包括缺失键，订阅注册时解析。
 Core 的 `select(document, selector, equality?)` 追踪实际读取，在选择分支改变时更新
@@ -84,9 +87,14 @@ apply(changes, { expectedRevision }) 拒绝缺失或不匹配的本地基线；
 observerErrors 属于已提交结果。
 
 集合边界使用 `observe(document, path => path.tasks)`，纯派生值使用
-`derive([tasks, filter], (tasks, filter) => ...)`。定义是惰性的，由一个
-`createProjectionRuntime({ onError })` owner 物化和管理。保留状态、反向索引和
-keyed patch 放在隔离的 `doxum/advanced` incremental 入口。生命周期、draft、
+`derive({ tasks, filter }, ({ tasks, filter }) => ...)`。定义是惰性的，由一个
+`createProjectionRuntime({ onError })` owner 物化和管理。当一个 keyed source 决定
+output key/order 时，用 `derive.keyed(entries, entry => entry.label)` 独立映射每个
+entry；跨 collection 的动态 key lookup 继续在同一个 derivation 中用命名依赖对象声明：
+普通 Projection 成员是全局依赖，`{ source, key }` 成员是逐 output key lookup，selector
+接收 `(entry, key, dependencies)`。Runtime 拥有 binding/reverse index，producer DAG
+仍保持显式。只有 `derive.keyed` 无法表达的 retained state、自定义跨 key index 或
+keyed patch 才放到隔离的 `doxum/advanced` incremental 入口。生命周期、draft、
 selector 追踪、batch 与故障恢复见 [Projection 参考](projections.zh-CN.md)。
 tree 结构复用同一套 projection source 协议：`path.tree.rootId` 是 scalar，
 `path.tree.nodes` 是 keyed collection，`path.tree.nodes.item(id)` 是单节点 value。

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

@@ -1,5 +1,8 @@
 # Runtime Invariants
 
+Public call shapes belong in [api.en.md](api.en.md); keep this file limited to
+implementation invariants that affect design and review decisions.
+
 1. createDocument owns canonical state; Draft, apply and replace share MutationSession.
    runtime owns one execution/rollback/seal/publish boundary, also used by history.
    mutation/operations groups table/list/order/tree/replay commands by domain; session
@@ -21,23 +24,44 @@
 5. Atomic equality is Object.is; canonical structure retains atomic references under
    ownership contract. Snapshots copy structure and share readonly payloads, as do
    commits and history. No payload cloning or publication freezing. Validators receive
-   original inputs and must be pure; successful output is ignored.
+   original inputs and must be pure; function validators are predicates/assertions and
+   Standard Schema success may not transform the canonical value.
 6. List identity is a stable key; replacement retains it. Anchor owns ordering.
    Tree owns reciprocal, connected, acyclic, empty-or-single-root topology.
-7. ObjectNode owns schema identity; one RuntimeContext owns instance identity for the
-   runtime, history and read-only aliases. The shared path compiler and Core impact target
+7. Public `Schema` / `ObjectSchema` handles own schema identity while concrete nodes stay
+   internal. Schema model, path compilation, compiled layout and value validation/copy
+   have separate internal owners; foundation model/layout modules do not depend on
+   document/projection Runtime code. One RuntimeContext owns instance identity for the runtime, history and
+   `document.readonly()` aliases. The shared path compiler and Core impact target
    algorithms own addressing/identity/equality/bucketing and exact matching. React sees
    only Readable/select contracts. Notification matches grouped changes directly without
    building commit impact indexes.
 8. Apply requires expectedRevision and captures actual local old state. Local reset is
    reversible; remote commits invalidate history. Groups travel in one session.
-9. Projections declare sources and settle before listeners. Notification failures leave
-   commits accepted. Batch defers projection publication, not document commits/listeners.
+9. Projections declare producer sources and settle before listeners. The producer DAG
+   remains static. `derive.keyed` declares extra sources in one named dependency object;
+   `{ source, key }` members may bind each output key to a key in an explicitly declared
+   keyed source. The materialized Runtime owns those bindings and reverse indexes,
+   including bindings to currently missing source entries. Processors do not create graph
+   dependencies through imperative Runtime reads. A scope adds lifecycle ownership only
+   through `scope.own`; scoped definitions may depend on root definitions, while root and
+   sibling scopes cannot depend on scoped definitions. Notification failures leave commits
+   accepted. Batch defers projection publication, not document commits/listeners.
+   Lazy definition metadata does not materialize sources. Input, observe and source
+   materialization remain separate boundaries. One output object owns staged/published
+   state, revision, listeners and graph-facing consumer capability; scheduler alone
+   attaches/detaches dependency edges. Collection-input callback/equality failure installs
+   no partial Runtime-local state. Cleanup is exhaustive after ownership is detached;
+   initialization failure releases already-created projection resources and preserves the
+   original error. Document dirty/pending state has one write owner; structural
+   materialization only reads it.
 10. Local sync uses Web Lock leadership and contiguous durable sequence. Writes precede
     asynchronous persistence. Version 5 / format 3 rejects old databases without editing
     them. External replace and remote apply are prohibited while attached.
 11. Core is framework-neutral. Public exports are deliberate; root dist is generated.
 12. Test malformed input, partial rollback, history, impact, disposal and bounded work.
+    Dependency de-duplication uses target-owned canonical bucketing plus exact equality;
+    do not fall back to a linear all-target scan or an ad-hoc string path grammar.
     Delete obsolete APIs and parallel protocols.
 
 Network intent, authorization, collaborative undo and persist-before-visible acceptance

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

@@ -1,5 +1,7 @@
 # Runtime 不变量
 
+公开调用形态统一放在 [api.zh-CN.md](api.zh-CN.md)；本文只保留影响实现和 review 的不变量。
+
 1. createDocument 唯一拥有 canonical state；Draft、apply、replace 共用 MutationSession。
    runtime 统一执行、回滚、seal、发布边界，history 同样复用。
    mutation/operations 按 table/list/order/tree/replay 分类完整操作，session 持有写入内核。
@@ -15,21 +17,37 @@
    capture、restore 和按域 seal 分离；当前顺序确实变化后才复制最终 order，净变化为零也保留执行期间的回滚基线。
 5. 原子值按 Object.is 比较，canonical 结构依所有权契约保留原子引用；
    快照只复制结构，payload 与 commit、history 共享且只读，不做深复制或发布冻结。
-   校验器直接读取原始输入，必须纯同步，成功返回值被忽略。
+   validator 直接读取原始输入且必须纯同步；函数形式是 predicate/assertion，
+   Standard Schema 成功时不能 transform canonical value。
 6. list 以稳定键标记身份，替换值必须保留键。anchor 拥有排序语义；
    tree 拥有双向一致、连通、无环、空树或单根的拓扑约束。
-7. ObjectNode 拥有定义身份；runtime、history 和只读 alias 共享唯一 RuntimeContext
-   实例身份。共享路径 compiler 与 Core impact target 算法拥有寻址、身份、相等、
+7. 公开 `Schema` / `ObjectSchema` handle 拥有定义身份，concrete node 留在内部；
+   schema model、path compiler、compiled layout、value validation/copy 各有唯一内部 owner，
+   foundation model/layout 不依赖 document/projection Runtime。runtime、history 和
+   `document.readonly()` alias 共享唯一 RuntimeContext 实例身份。
+   共享路径 compiler 与 Core impact target 算法拥有寻址、身份、相等、
    分桶和精确匹配；React 只消费 Readable/select 契约。通知直接匹配分组变化，
    不构建 commit impact 索引。
 8. apply 要求 expectedRevision，记录本地真实旧状态。本地 reset 可撤销，
    remote commit 使 history 失效；group 在单个 session 中旅行。
-9. projection 显式声明 source，先于监听结算。通知失败不撤销提交；
-   batch 推迟投影发布，不推迟文档提交与文档监听。
+9. projection 显式声明 producer source，先于监听结算，producer DAG 保持静态。
+   `derive.keyed` 用一个命名依赖对象声明额外 source；其中 `{ source, key }` 成员可以
+   把每个 output key 绑定到已显式声明 keyed source 的某个 key。物化后的 Runtime
+   拥有这些 binding 和 reverse index，包括当前尚不存在的 source entry。processor
+   不通过 imperative Runtime read 创建图依赖。scope 只通过 `scope.own` 增加 lifecycle
+   ownership；scoped definition 可以依赖 root definition，root 与 sibling scope 不能依赖
+   scoped definition。通知失败不撤销提交；batch 推迟投影发布，不推迟文档提交与文档监听。
+   lazy definition metadata 不负责物化 source；input、observe、source materialization 分层。
+   一个 output object 同时拥有 staged/published state、revision、listener 和 graph-facing
+   consumer capability，只有 scheduler 连接/断开 dependency edge。collection input 的 callback
+   或 entry equality 抛错时不得安装部分 Runtime-local state。cleanup 先摘除 ownership，再穷尽
+   释放；初始化失败释放已创建的 projection resource，同时保留原始异常。document dirty/pending
+   state 只有一个写 owner，structural materialization 只读该状态。
 10. local-sync 使用 Web Lock 领导权和连续 durable seq，先可见后异步持久化。
     版本 5 / 格式 3 拒绝旧数据库并保留原数据，附着期间禁止外部 replace 和 remote apply。
 11. core 框架无关，公开导出需明确用途；根 dist 为构建产物。
 12. 测试 malformed 输入、部分失败回滚、history、impact、dispose 和大集合工作量。
-    删除旧 API 和平行协议。
+    dependency 去重使用 impact target owner 提供的 canonical bucket，再做精确 equality；
+    不得退回全量线性扫描或新增字符串 path grammar。删除旧 API 和平行协议。
 
 网络意图、鉴权、协作撤销、先持久化后可见属于独立需求，不是隐藏 runtime 能力。

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

@@ -1,5 +1,7 @@
 # Doxum Patterns
 
+Exact call shapes and callback fields are listed in the [API reference](api.en.md).
+
 ## Payload Or Structure
 
 ```ts
@@ -19,15 +21,27 @@ Edit position.x, replace stroke whole, and use rows.replace(key, value) for keye
 const model = object({
   entries: map(object({ rows: table(object({ title: field<string>() })) })),
 });
-const document = createDocument({ schema: model, initial: { entries: {} } });
+const document = createDocument({
+  schema: model,
+  initial: {
+    entries: {
+      a: { rows: { ids: ['x'], byId: { x: { title: 'First' } } } },
+    },
+  },
+});
 document.update(draft => {
-  draft.entries.put('a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
-  draft.entries.get('a')!.rows.get('x')!.title = 'Updated';
+  const entry = draft.entries.get('a')!;
+  replace(entry, 'rows', {
+    ids: ['y'],
+    byId: { y: { title: 'Replacement' } },
+  });
 });
 ```
 
-Map entries use put. Use top-level replace for object/variant members whose Draft
-type contains collection tools; collection replace(next) handles whole containers.
+Use top-level `replace(parent, key, value)` for object/variant members whose Draft
+type contains collection tools. Map membership still uses `put`/`remove`; a
+collection's own `replace(next)` handles replacement when the collection itself is
+the mutation target.
 
 ## Domain Keys
 
@@ -45,7 +59,7 @@ const model = object({ people: map(object({ name: field(text) }), { key: personI
 const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-Brands flow through map/table methods, symbolic paths and collection impact.
+Branded key types flow through map/table methods, symbolic paths and collection impact.
 
 ## Ordered Edits, History And Replay
 
@@ -85,18 +99,64 @@ envelopes or treat its container address as whole-container invalidation.
 ## Projection And React
 
 ```ts
-const tasks = observe(document, path => path.tasks);
-const titles = derive([tasks], tasks => new Map([...tasks].map(([id, task]) => [id, task.title])));
-const total = derive([titles], titles => titles.size);
-const zoom = input(1);
-const scaled = derive([total, zoom], (total, zoom) => total * zoom);
+const rows = observe(document, path => path.rows);
+const metadata = observe(document, path => path.metadata);
+const density = input<'compact' | 'comfortable'>('comfortable');
+
+const labels = derive.keyed(rows, row => row.label);
+const decorated = derive.keyed(
+  rows,
+  {
+    meta: { source: metadata, key: row => row.metadataId },
+    density,
+  },
+  (row, _rowId, { meta, density }) => formatRow(row, meta, density)
+);
+const count = derive({ labels }, ({ labels }) => labels.size);
+const selection = input.collection<RowId, boolean>();
 const runtime = createProjectionRuntime({ onError: console.error });
-runtime.get(scaled);
-const title = runtime.get(tasks).get(taskId);
+runtime.read(decorated);
+runtime.read(count);
+runtime.update(density, 'compact');
+runtime.update(selection, draft => draft.set(rowId, true));
+```
+
+Use named-object `derive` for aggregate values. Use `derive.keyed` when one keyed
+driver owns output keys/order. Its named dependency form handles dynamic keyed lookups;
+the Runtime owns the binding/reverse index. Use `input.collection` for Runtime-local
+keyed UI/application state rather than canonical document state.
+
+Provide the Runtime or a scope through `ProjectionProvider`. `useProjection` reads
+projections, including `useProjection(projection, selector, equality?)`; `useInput`
+handles both scalar and collection inputs. Document selectors use
+`useDocumentSelector(document, selector, equality?)` independently of the provider.
+
+## Multi-output incremental processor
+
+Use this only when outputs share retained state or cross-key work that pure `derive`
+and `derive.keyed` cannot express:
+
+```ts
+const render = incremental.group(
+  { scene },
+  {
+    output: define => ({
+      cards: define.collection<string, Card>(),
+      count: define.value<number>(),
+    }),
+    state: () => ({ runs: 0 }),
+    process: ({ values, output, state }) => {
+      state.runs++;
+      const cards = buildCards(values.scene);
+      for (const [id, card] of cards) output.cards.set(id, card);
+      output.cards.order([...cards.keys()]);
+      output.count.set(cards.size);
+    },
+  }
+);
 ```
 
-Provide the Runtime through `ProjectionProvider`, then use `useProjection` for
-projection definitions and `useProjection(projection, selector)` for keyed reads.
-`useInput` returns a value and setter. Advanced collection processors in `doxum/advanced` stage
-`output.set/remove/order` and use scoped previous/next reads. Processor
-dependencies remain explicit even though React selectors track actual reads.
+`define.value` / `define.collection` exist only inside the `output` declaration.
+The returned nested object mirrors ordinary Projection leaves from one processor.
+Dependencies are named; declare `state()` only when retained state is needed. Runtime
+recovery recreates declared state after a processor fault.

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

@@ -1,5 +1,7 @@
 # Doxum 常见模式
 
+精确调用形态和 callback 字段见 [API 参考](api.zh-CN.md)。
+
 ## 原子值与结构
 
 ```ts
@@ -19,15 +21,26 @@ position.x 细粒度赋值；stroke 整体替换；rows.replace(key, value) 按
 const model = object({
   entries: map(object({ rows: table(object({ title: field<string>() })) })),
 });
-const document = createDocument({ schema: model, initial: { entries: {} } });
+const document = createDocument({
+  schema: model,
+  initial: {
+    entries: {
+      a: { rows: { ids: ['x'], byId: { x: { title: 'First' } } } },
+    },
+  },
+});
 document.update(draft => {
-  draft.entries.put('a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
-  draft.entries.get('a')!.rows.get('x')!.title = 'Updated';
+  const entry = draft.entries.get('a')!;
+  replace(entry, 'rows', {
+    ids: ['y'],
+    byId: { y: { title: 'Replacement' } },
+  });
 });
 ```
 
-map 条目使用 put。Draft 类型含集合方法的 object/variant 成员使用顶层 replace；
-集合整体替换使用集合自身的 replace(next)，并经同一 mutation session 修改。
+Draft 类型含集合方法的 object/variant 成员使用顶层 `replace(parent, key, value)`；
+map membership 仍使用 `put`/`remove`。当集合本身就是 mutation target 时，整体替换
+使用集合自身的 `replace(next)`。
 
 ## 领域键
 
@@ -45,7 +58,7 @@ const model = object({ people: map(object({ name: field(text) }), { key: personI
 const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-品牌类型贯穿 map/table 方法、符号路径和 collection impact。
+品牌键类型贯穿 map/table 方法、符号路径和 collection impact。
 
 ## 顺序、History 与重放
 
@@ -84,18 +97,63 @@ document.apply(
 ## 投影与 React
 
 ```ts
-const tasks = observe(document, path => path.tasks);
-const titles = derive([tasks], tasks => new Map([...tasks].map(([id, task]) => [id, task.title])));
-const total = derive([titles], titles => titles.size);
-const zoom = input(1);
-const scaled = derive([total, zoom], (total, zoom) => total * zoom);
+const rows = observe(document, path => path.rows);
+const metadata = observe(document, path => path.metadata);
+const density = input<'compact' | 'comfortable'>('comfortable');
+
+const labels = derive.keyed(rows, row => row.label);
+const decorated = derive.keyed(
+  rows,
+  {
+    meta: { source: metadata, key: row => row.metadataId },
+    density,
+  },
+  (row, _rowId, { meta, density }) => formatRow(row, meta, density)
+);
+const count = derive({ labels }, ({ labels }) => labels.size);
+const selection = input.collection<RowId, boolean>();
 const runtime = createProjectionRuntime({ onError: console.error });
-runtime.get(scaled);
-const title = runtime.get(tasks).get(taskId);
+runtime.read(decorated);
+runtime.read(count);
+runtime.update(density, 'compact');
+runtime.update(selection, draft => draft.set(rowId, true));
+```
+
+聚合值使用 named-object `derive`。一个 keyed driver 拥有 output key/order 时使用
+`derive.keyed`；named dependency form 负责 dynamic keyed lookup，binding/reverse
+index 由 Runtime 拥有。`input.collection` 用于 Runtime-local 的 keyed UI/application
+state，不进入 canonical document state。
+
+React 用 `ProjectionProvider` 提供 Runtime 或 scope；`useProjection` 支持
+`useProjection(projection, selector, equality?)`，`useInput` 同时支持 scalar 与
+collection input。Document selector 独立使用
+`useDocumentSelector(document, selector, equality?)`。
+
+## 多输出 incremental processor
+
+只有 pure `derive` / `derive.keyed` 无法表达共享 retained state 或 cross-key work 时使用：
+
+```ts
+const render = incremental.group(
+  { scene },
+  {
+    output: define => ({
+      cards: define.collection<string, Card>(),
+      count: define.value<number>(),
+    }),
+    state: () => ({ runs: 0 }),
+    process: ({ values, output, state }) => {
+      state.runs++;
+      const cards = buildCards(values.scene);
+      for (const [id, card] of cards) output.cards.set(id, card);
+      output.cards.order([...cards.keys()]);
+      output.count.set(cards.size);
+    },
+  }
+);
 ```
 
-React 使用 `ProjectionProvider` 提供 Runtime，再用 `useProjection` 读取 Projection，单键读取写成
-`useProjection(projection, selector)`；`useInput` 返回值和 setter。高级集合 processor
-从 `doxum/advanced` 引入，在同步 callback 中使用
-`output.set/remove/order` 与 previous/next。Processor 依赖仍显式声明，
-React selector 追踪只属于消费端。
+`define.value` / `define.collection` 只存在于 `output` 声明 callback 内，返回的嵌套
+object 会映射为同一 processor 的普通 Projection leaves。依赖按名称读取；只有需要
+retained state 时才声明 `state()`。processor fault 后由 Runtime 重新创建已声明的 state
+并恢复。