doxum 0.1.7 → 0.1.9

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

@@ -1,97 +1,34 @@
-# Doxum Runtime 不变量
-
-修改或审查 mutation、addressing、impact、notification、history、tree 或 projection 前应阅读本页。这些是设计边界，而不是可选的代码风格。
-
-## 唯一的 canonical 写入权威
-
-`createDocument` 拥有 canonical mutable document state。canonical write 只能通过 `runtime.update`、`runtime.apply` 或 `runtime.replace`。`runtime.prepare` 可以复用同一 mutation session 产生随后会回滚的未提交 operation batch，供 durable adapter 使用；它不是第二条写入路径。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 必须保持稳定。
-
-## 派生状态应声明，而不是由调用方同步
-
-ProjectionCollection 和 ProjectionValue 共用显式 source 图与发布机制。只有 scoped processor 写入派生输出。应用根据原生 impact 选择候选 key，Doxum 拥有最终 change、equality、revision 和 notification。不能泄漏可变私有索引，也不能保留 scoped reader/writer。update 必须同步。
-
-受影响节点全部 settle 后再通知。失败丢弃候选输出，限一次全新 build 恢复，持续失败阻断下游；listener 错误逐个隔离。处理和通知期间禁止 source write。显式 batch 延迟派生图发布，不延迟 canonical commit 或 document listener，不承诺 source rollback。owner 负责 dispose，仍有消费者的节点不能单独释放。
-
-## Framework 与产品边界
-
-`core` 必须保持 framework-neutral。`doxum/react` 是从 core 到 React 的单向 adapter；core 不能 import React 或 UI 概念。`doxum/local-sync` 是附着到应用自有 runtime 的可选浏览器 attachment：它会恢复 IndexedDB checkpoint/tail，以 document Web Lock 选出唯一 leader，并通过一个很小的内部同步写入 policy 拒绝 follower mutation，而不改变 runtime API。leader 监听已完成的 local、system 与 history commit，将 JSON operation batch 异步追加到日志，并且只广播 head 提示。follower 从 durable tail 顺序读取并按 `remote` apply，因此 history 会失效。没有 pending queue、rebase、actor history 或 attachment 专属的 undo API。附着期间，外部 `replace` 与标记为 `remote` 的外部 `apply` 都会被拒绝，因为只有 operation command 能 append；attachment 的 hydration 与 replay lease 是唯一受信任例外。它不会承诺严格 durability；应用在需要观察持久化或追赶时使用 `state.current()`、`onError` 与 `flush()`。Doxum 有意不决定网络同步、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 解释是否被删除，而不是为了兼容继续保留？
+# Runtime 不变量
+
+1. createDocument 唯一拥有 canonical state；Draft、apply、replace 共用 MutationSession。
+   runtime 统一执行、回滚、seal、发布边界，history 同样复用。
+   mutation/operations 按 table/list/order/tree/replay 分类完整操作，session 持有写入内核。
+   scope 经 session 绑定已解析事实，同 generation 复用 handle；这些均为内部实现边界。
+2. 公共读写同步且有作用域，禁止重入写入。失败恢复之前全部工作；普通异常原样抛出，
+   TransactionRejected 转换为 application issues。内部 readWith 返回借用 reader，
+   reader、子 proxy 和 collection method 不得逃逸同步回调。
+3. mutation/changes.ts 统一解析 unknown ChangeSet；schema 为寻址真值。
+   拒绝父子重叠事实与同地址重复分组。逐容器安装成员及可选顺序，不接受独立 order 记录。
+4. ChangeRecorder 按所属容器分组记录首次成员旧值，唯一拥有顺序基线和触及树节点。
+   有序组一次发布 members 与 order；树容器没有普通成员 layout，拒绝 members replay。
+   树命令直接捕获触及节点，不经过 session 回调协议。回滚不调用用户回调或校验器，seal 只发布净变化。
+   capture、restore 和按域 seal 分离；当前顺序确实变化后才复制最终 order，净变化为零也保留执行期间的回滚基线。
+5. 原子值按 Object.is 比较，canonical 结构依所有权契约保留原子引用；
+   快照只复制结构，payload 与 commit、history 共享且只读，不做深复制或发布冻结。
+   校验器直接读取原始输入，必须纯同步，成功返回值被忽略。
+6. list 以稳定键标记身份，替换值必须保留键。anchor 拥有排序语义；
+   tree 拥有双向一致、连通、无环、空树或单根的拓扑约束。
+7. ObjectNode 拥有定义身份，runtime 拥有实例身份；共享路径 compiler 和
+   impact-target 拥有寻址、身份、相等、分桶和精确匹配，React 也遵守此边界。
+   通知直接匹配分组变化，不构建 commit impact 索引。
+8. apply 要求 expectedRevision，记录本地真实旧状态。本地 reset 可撤销，
+   remote commit 使 history 失效；group 在单个 session 中旅行。
+9. projection 显式声明 source，先于监听结算。通知失败不撤销提交；
+   batch 推迟投影发布，不推迟文档提交与文档监听。
+10. local-sync 使用 Web Lock 领导权和连续 durable seq，先可见后异步持久化。
+    版本 5 / 格式 3 拒绝旧数据库并保留原数据，附着期间禁止外部 replace 和 remote apply。
+11. core 框架无关，公开导出需明确用途；根 dist 为构建产物。
+12. 测试 malformed 输入、部分失败回滚、history、impact、dispose 和大集合工作量。
+    删除旧 API 和平行协议。
+
+网络意图、鉴权、协作撤销、先持久化后可见属于独立需求，不是隐藏 runtime 能力。

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

@@ -1,256 +1,104 @@
 # 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          |
-| Ordered entities                | `table(entity)`            | `{ ids, byId }`     | `create`, `item`, `remove`, `move`           |
-| Unordered entities              | `map(entity)`              | id record           | `create`, `item`, `remove`                   |
-| 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`.
-
-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.
+## Payload Or Structure
 
 ```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 }>(),
+const point = object({ x: field<number>(), y: field<number>() });
+const model = object({
+  position: point,
+  stroke: field<readonly { x: number; y: number }[]>(),
+  rows: list(field<{ id: string; label: string }>(), { keyOf: row => row.id }),
 });
 ```
 
-## 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({
-        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({
-      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
+Edit position.x, replace stroke whole, use rows.set(key, value) for keyed item edits.
 
-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.
+## Complex Replacement
 
 ```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' });
+const model = object({
+  entries: map(object({ rows: table(object({ title: field<string>() })) })),
+});
+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';
 });
 ```
 
-## Work with trees as one invariant
+TypeScript cannot express different read/write types for mapped properties.
+assign checks Infer replacement data and uses the same mutation session.
 
-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.
+## Domain Keys
 
 ```ts
-runtime.update(tx => {
-  tx.write.outline.insert('root', { title: 'Project' });
-  tx.write.outline.insert('plan', { title: 'Plan' }, { parentId: 'root' });
-  tx.write.outline.move('plan', { parentId: 'root', index: 0 });
-  tx.write.outline.set('plan', { title: 'Plan release' });
-});
+type PersonId = string & { readonly __person: unique symbol };
+const personId = (value: unknown): PersonId => {
+  if (typeof value !== 'string' || !value.startsWith('person:')) throw new Error('Person ID');
+  return value as PersonId;
+};
+const text = (value: unknown): string => {
+  if (typeof value !== 'string') throw new Error('String required');
+  return value;
+};
+const model = object({ people: map(object({ name: field(text) }), { key: personId }) });
+const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-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
+Brands flow through indexed access, table methods, symbolic paths and collection impact.
 
-Create selectors once with their owning schema. This creates a stable public
-contract for subscriptions and impact interpretation.
+## Ordered Edits, History And Replay
 
-```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 table.create/remove/move with anchors such as { at: 'start' } or { before: id }.
+Tree insert/move accept { parentId, index }; index is the final position after removal.
+Never directly edit topology records.
 
-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.
+A history group begins with document.history.group(); end() groups completed commits,
+cancel() restores its start. undo/redo travel complete ChangeSets atomically.
+Apply incoming changes with an expectedRevision and adapter-validated transport order.
+Remote commits invalidate local history. Local revision is not a distributed clock.
 
-## Build explicit projections
+Incoming member changes share the owning container address:
 
 ```ts
-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 }
+document.apply(
+  {
+    changes: [
+      {
+        kind: 'members',
+        at: ['tasks', 'a'],
+        members: [
+          { key: 'complete', kind: 'updated', before: false, after: true },
+          { key: 'title', kind: 'updated', before: 'First', after: 'Done' },
+        ],
+      },
+    ],
+  },
+  { expectedRevision: document.revision() }
 );
-const noteCount = projection.value({ notes }, ({ notes }) => notes.read.ids().length);
 ```
 
-Use map for one-to-one document or projection collection transforms. For custom indexes, use
-`projection.collection<Item>()(spec)` with declared sources and scoped writer.set/remove/order/replace.
-Its previous and next readers separate published values from staged writes.
-Use document collection `reset`, `candidates.keys` and `candidates.orderDirty`,
-or inspect native commit impacts and upstream collection changes for algorithms
-that need them. Candidates include net-zero changes; read final state.
-Dependencies are explicit and fixed, not learned
-from reads. Doxum determines final changes through equality.
+Use one group per container. Added members carry only after, removed members only
+before; present undefined is still a value. Never expand a group into legacy value
+envelopes or treat its container address as whole-container invalidation.
 
-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.
+## Projection And React
 
-## 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>
-  );
-}
+```ts
+const titles = project(
+  document,
+  path => path.tasks,
+  (_id, task) => task.title
+);
+const total = project({ titles }, ({ titles }) => titles.ids().length);
+const zoom = input(1);
+const scaled = project({ total, zoom }, ({ total, zoom }) => total * zoom);
+const store = createProjectionStore({ onError: console.error });
+store.get(scaled);
 ```
 
-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.
+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.