doxum 0.1.23 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.23",
+  "version": "0.1.26",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",
@@ -79,11 +79,14 @@
     "vitest": "^4.0.16"
   },
   "scripts": {
-    "build": "tsdown --config tsdown.config.ts",
+    "build": "tsdown --config tsdown.config.ts && node scripts/check-build-exports.mjs && pnpm run check:declaration-portability",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --config vitest.config.ts",
-    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run check:projection-surface",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run check:public-types && pnpm run test && pnpm run check:projection-surface && pnpm run check:runtime-imports",
     "check:projection-surface": "node scripts/check-projection-surface.mjs",
+    "check:runtime-imports": "node scripts/check-runtime-imports.mjs",
+    "check:public-types": "tsc -p tsconfig.public-api.json --noEmit",
+    "check:declaration-portability": "tsc -p tsconfig.declaration-portability.json && node scripts/check-declaration-portability.mjs",
     "bench": "vitest bench --config vitest.bench.config.ts",
     "profile": "node --expose-gc --import tsx core/bench/profile.ts",
     "format": "prettier --write --ignore-unknown .",

package/skills/doxum-runtime/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: doxum-runtime
-description: 'Use doxum and doxum/react for schemas, scoped draft updates, ChangeSets, history, projections, subscriptions and React integration.'
+description: 'Use Doxum core, advanced projections, React, and local-sync for schemas, document state, ChangeSets, history, projections, subscriptions, persistence, and adapters.'
 ---
 
 # Doxum Runtime
 
 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 exact public call shapes, exported package surface, callback contexts, result
+types, and supported errors, read the [API reference](references/api.en.md) or
+[中文 API 参考](references/api.zh-CN.md) instead of implementation source.
 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).
@@ -36,13 +39,34 @@ 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.
+- `Schema` / `ObjectSchema` are portable schema handles. Export inferred schemas
+  directly; application code should not need `ReturnType<typeof object>` or internal
+  node types to make declarations portable.
 - Projection definitions are lazy; one ProjectionRuntime owns all materialized
   producers, outputs, scheduling and source attachments for that Runtime.
-  Use tuple `derive` for pure values. Advanced `incremental` processors declare every
-  source, own any forward/reverse dependency indexes, derive from final batched source
-  state, and recover from resets internally. Core projections never track reads
-  automatically; React selectors do through `ProjectionProvider` and
-  `useProjection(projection, selector)`.
+  `KeyedProjection<K,V>` is the single public keyed projection handle. Collection
+  `observe`, `derive.keyed`, `incremental.collection`, group collection leaves and
+  `CollectionInput<K,V>` all use that same keyed capability.
+  Use named-object `derive` for pure aggregate values. Use `derive.keyed` when one keyed
+  driver owns the output key domain/order: per-entry equality suppresses unchanged
+  selected values. Its dependency form uses a named object: plain Projection members
+  invalidate the driver key set, while `{ source, key }` members let the Runtime own
+  per-output-key source bindings and reverse lookup. Selectors receive
+  `(entry, key)` or `(entry, key, dependencies)`. The producer graph remains explicit and static;
+  processors never perform imperative Runtime reads to discover dependencies.
+  `input.collection` edits have a strong exception boundary: callback or per-entry
+  equality failure leaves both the published value and the next draft unchanged.
+  A `ProjectionScope` only adds lifecycle ownership through `scope.own(...)`; create
+  definitions with the root declaration APIs, then own a projection or static output tree
+  before that definition is first materialized as a root.
+  Use advanced `incremental` only for retained state or cross-key coordination that
+  cannot be expressed by `derive.keyed`. React selector tracking remains a consumer
+  concern through `ProjectionProvider` and `useProjection(projection, selector)`.
+- Advanced incremental definitions always declare `process`; `state()` is present only
+  when retained state is actually needed. `incremental.group` declares its static
+  output tree through the synchronous `output` callback. `define.value` and
+  `define.collection` are callback methods, not separate imports; every returned leaf
+  is a `Projection<T>` or `KeyedProjection<K,V>` from the same producer.
 - Observer errors leave commits accepted. Do not retry as if they rolled back.
 - Core stays framework-neutral; adapters consume standard `Readable`,
   document `select`, and projection readables without internal target/address protocols.
@@ -50,4 +74,5 @@ Before runtime changes read [invariants](references/invariants.en.md) or
   collaborative undo belong at a separate boundary.
 
 Update examples and tests when behavior changes. Never add compatibility APIs,
-a second path grammar or another writable derived cache.
+a second path grammar, a parallel join/dependency protocol, or another writable
+derived cache.

package/skills/doxum-runtime/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Doxum Runtime'
-  short_description: 'Build, modify, and review Doxum runtime code safely.'
+  short_description: 'Build and review Doxum core, projections, React, and local-sync.'
   default_prompt: 'Use $doxum-runtime to implement this Doxum feature while preserving its runtime invariants.'

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

@@ -0,0 +1,249 @@
+# Public API Reference
+
+Use this as the compact public-contract lookup. For projection lifecycle and examples,
+read [projections](projections.en.md); for modeling choices, read the [guide](guide.en.md).
+
+## Package entry points
+
+| Package            | Purpose                                                                 |
+| ------------------ | ----------------------------------------------------------------------- |
+| `doxum`            | schema, canonical document runtime, reads, history, impact, projections |
+| `doxum/advanced`   | retained-state and multi-output projection processors                   |
+| `doxum/react`      | React adapters over Core capabilities                                   |
+| `doxum/local-sync` | IndexedDB persistence and browser leader/follower coordination          |
+
+## `doxum`
+
+### Schema
+
+| API                       | Contract                                                               |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `field<T>(validator?)`    | Atomic payload. Replace whole; payload interior is readonly.           |
+| `optional(schema)`        | Optional field/variant/map/list/tree member.                           |
+| `object(shape)`           | Fixed declared members; returns opaque `ObjectSchema<T>`.              |
+| `variant(tag, variants)`  | Tagged union of object branches.                                       |
+| `map(value, { key }?)`    | Dynamic keyed record.                                                  |
+| `table(entity, { key }?)` | Ordered keyed object/variant entities stored as `{ ids, byId }`.       |
+| `list(field, { keyOf })`  | Ordered array with stable string identity.                             |
+| `tree(field)`             | Empty-or-single-root tree; optional field means optional node payload. |
+| `parse(schema, input)`    | Validate unknown input and copy schema structure.                      |
+
+Public schema types are `Schema<T>`, `ObjectSchema<T>`, `Infer<S>`, `ReadonlyValue<T>`,
+`Validator<T>`, `SchemaPath<S>`, `PathValueOf<P>`, `DocumentAnchor`,
+`DocumentListConfig<T>`, `DocumentTreeNode<T>` and `DocumentTreeValue<T>`.
+Concrete node representation types are internal.
+`Schema` / `ObjectSchema` are declaration-portable handles; downstream packages can
+export inferred schema constants directly without `ReturnType` wrappers.
+
+`Validator<T>` is validation-only. A function validator is a predicate/assertion:
+`true` or `undefined` succeeds, `false` rejects, and an assertion may throw.
+A Standard Schema validator must return the original value by identity on success;
+transformed output is rejected. Validators are synchronous and must not mutate input.
+
+Draft collection methods:
+
+| Container | Read                                         | Write                                                                        |
+| --------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
+| map       | `get`, `has`, `ids`                          | `put`, `remove`, `replace(next)`                                             |
+| table     | `get`, `has`, `ids`                          | `create`, `remove`, `move`, `reorder`, `replace(id,value)`, `replace(next)`  |
+| list      | `get`, `has`, `ids`                          | `insert`, `remove`, `move`, `reorder`, `replace(key,value)`, `replace(next)` |
+| tree      | `rootId`, `get`, `has`, `parent`, `children` | `insert`, `move`, `remove`, `replace(id,value)`, `replace(next)`             |
+
+`replace(parent, key, value)` replaces one object/variant member with plain `Infer` data.
+`document.replace(value)` is a whole-document reset and remains a separate operation.
+
+### Document runtime
+
+```ts
+const document = createDocument({ schema, initial, history: { capacity: 100 } });
+```
+
+`DocumentRuntime<S>` exposes:
+
+- `schema`, `revision()`, `snapshot()` and `readonly()`;
+- `update(run, { source?, history? }?)` for synchronous atomic Draft work;
+- `apply(changes, { expectedRevision, source?: 'local' | 'system', history? })`, or
+  `apply(changes, { expectedRevision, source: 'remote' })` for remote replay;
+- `replace(value, { source? }?)` for a whole-document reset;
+- `subscribe(listener)` and `subscribe(path | paths, listener)`;
+- `history.undo()`, `redo()`, `clear()`, `group()`;
+- `dispose()`.
+
+`document.readonly()` returns `ReadonlyDocument<S>`, which has only `revision()` and
+document commit/path subscriptions. It is the capability-stripped document boundary.
+
+`update` returns `TransactionResult`; `apply`, whole-document `replace`, history travel
+and group cancellation return `OperationResult`. Result status is `committed`,
+`unchanged`, or `rejected`. Throw `TransactionRejected` for expected application
+rejection. Ordinary thrown values roll back and rethrow unchanged.
+
+Document errors are `TransactionRejected`, `DocumentReentrancyError` and
+`DocumentDisposedError`. Parsing failures use `ParseError` with `ParseIssue` data.
+
+### Reads and subscriptions
+
+| API                                     | Contract                                                  |
+| --------------------------------------- | --------------------------------------------------------- |
+| `read(document, selector)`              | One synchronous borrowed `Read`.                          |
+| `select(document, selector, equality?)` | Dynamic read-tracked `Readable<TResult>`.                 |
+| `snapshot(value)`                       | Export borrowed schema structure as stable readonly data. |
+
+`Readable<T>` has `current()`, `revision()` and `subscribe(listener)`.
+`select` rebinds dependencies when selector control flow changes and suppresses
+publication when `equality` reports the selected result unchanged.
+
+A commit has `revision`, `source`, `changes`, `impact`. Public change/impact types include
+`ChangeSet`, `Change`, `MemberChange`, `ValueTransition`, `DocumentCommit`,
+`DocumentImpact`, `CollectionImpact`, `MutationIssue` and result/diagnostic types.
+
+### Projections
+
+```ts
+const mode = input<'all' | 'open'>('all');
+const selection = input.collection<RowId, Selection>();
+const rows = observe(document, path => path.rows);
+const count = derive({ rows }, ({ rows }) => rows.size);
+```
+
+| API                                             | Contract                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------- |
+| `input(initial, equality?)`                     | Runtime-local writable scalar `Input<T>`.                           |
+| `input.collection<K,V>(initial?, equality?)`    | Runtime-local keyed `CollectionInput<K,V>` with per-entry equality. |
+| `observe(document)`                             | Whole-document Projection source.                                   |
+| `observe(document, path => ...)`                | Schema-path scalar or keyed Projection source.                      |
+| `observe(readable)`                             | Adapt a Doxum `Readable`.                                           |
+| `observe(externalSource)`                       | Adapt exported external value/collection source contracts.          |
+| `derive(dependencies, compute, equality?)`      | Pure value Projection with named dependencies.                      |
+| `derive.keyed(driver, select, equality?)`       | Preserve driver keys/order and project each entry.                  |
+| `derive.keyed(driver, deps, select, equality?)` | Keyed projection with named global/dynamic keyed dependencies.      |
+
+Dynamic keyed dependency syntax is
+`{ source: keyedProjection, key: (driverValue, driverKey) => sourceKey | undefined }`.
+The Runtime owns output-key to source-key bindings and reverse invalidation. This helper
+shape is inferred at the call site; no dedicated public helper type is required.
+Keyed selectors keep stable leading arguments: `(value, key)` without extra dependencies
+and `(value, key, dependencies)` when the named dependency object is present.
+
+`ProjectionRuntime` exposes:
+
+- `read(projection)`;
+- `select(projection)` and `select(projection, selector, equality?)`;
+- `update(input, nextValue)` for scalar `Input<T>`;
+- `update(collectionInput, draft => ...)` for `CollectionInput<K,V>`;
+- `batch(run, { cause? }?)`;
+- `scope()`;
+- `dispose()`.
+
+`input.collection` draft callbacks and per-entry equality run before accepted local
+state is installed. If either throws, the published collection and the next draft both
+remain at the pre-update state.
+
+`CollectionInputDraft` exposes `get`, `has`, `set`, `remove`. A throwing edit callback
+applies none of that edit. `ProjectionScope` mirrors `read`, `select`, `update`, `batch`,
+`dispose` and adds `own(projectionOrTree)` for lifecycle ownership of scalar/keyed inputs,
+derives and advanced output trees. One definition can belong to only one scope; call
+`own` before that definition is first materialized as a root.
+
+Public projection types are `Projection<T>`, `KeyedProjection<K,V>`, `Input<T>`,
+`CollectionInput<K,V>`, `CollectionInputDraft<K,V>`, `ProjectionRuntime`,
+`ProjectionScope`, plus the external source/event contracts. All keyed producers return
+`KeyedProjection<K,V>`; `CollectionInput<K,V>` is its writable Runtime-local form.
+`ProjectionError` exposes only `phase` and `cause`;
+`ProjectionDisposedError` represents disposed access.
+
+External value sources expose `kind: 'value'`, `current()`, `revision()`, `subscribe()`.
+External collection sources expose `kind: 'collection'` plus `get/has/ids` reads and
+optional `CollectionImpact` invalidation hints; the adapter derives exact
+`CollectionChange` transitions.
+
+## `doxum/advanced`
+
+Use advanced processors only when `derive` / `derive.keyed` cannot express retained
+state, cross-key indexes, or direct incremental output patching.
+
+All advanced functions use named dependencies and a closed definition object.
+
+```ts
+const total = incremental(
+  { rows },
+  {
+    state: () => ({ runs: 0 }),
+    process: ({ values, changes, previous, reset, cause, state }) => nextValue,
+  }
+);
+```
+
+`incremental.collection(dependencies, { process, state? })` adds keyed `previous`,
+`next`, and borrowed `output` with `set`, `remove`, `order`. `state()` is declared only
+when retained state is needed; stateless process contexts do not contain `state`.
+
+`incremental.group(dependencies, { output, process, state? })` declares several leaves:
+
+```ts
+const view = incremental.group(
+  { rows },
+  {
+    output: define => ({
+      cards: define.collection<RowId, Card>(),
+      count: define.value<number>(),
+    }),
+    state: () => ({ runs: 0 }),
+    process: ({ values, changes, previous, next, output, reset, cause, state }) => {},
+  }
+);
+```
+
+`define.collection<K,V>(equality?)` and `define.value<T>(equality?)` exist only inside
+`output`. The returned static object tree is mirrored with `KeyedProjection<K,V>`
+collection leaves and `Projection<T>` value leaves. Every declared descriptor must be
+returned exactly once.
+
+Normal source resets preserve retained state when declared. If a processor faults, the
+Runtime owns recovery: it recreates declared state and runs a reset evaluation. Stateless
+processors use the same recovery path without a state object. There is no public rebuild
+token or manual recovery protocol.
+
+Exported advanced helper types are the value/collection/group context and definition
+types, `CollectionChange`, and the declaration-safe `IncrementalGroupOutput` /
+`IncrementalGroupResult` type boundaries. Normal callers infer the latter two; internal
+scheduler/output plumbing is not part of the public contract.
+
+## `doxum/react`
+
+| API                                                  | Contract                                                       |
+| ---------------------------------------------------- | -------------------------------------------------------------- |
+| `ProjectionProvider`                                 | Provide `ProjectionRuntime` or `ProjectionScope`.              |
+| `useProjection(projection)`                          | Read a Projection.                                             |
+| `useProjection(projection, selector, equality?)`     | Selected Projection read.                                      |
+| `useInput(input)`                                    | Scalar `[value, setValue]` or collection `[map, updateDraft]`. |
+| `useDocumentSelector(document, selector, equality?)` | React adapter over Core document `select`.                     |
+| `useReadable(readable)`                              | Subscribe to any Doxum `Readable`.                             |
+| `useHistory(history)`                                | History state plus `undo` / `redo`.                            |
+
+## `doxum/local-sync`
+
+```ts
+const sync = await attachLocalSync({
+  runtime: document,
+  database: 'app',
+  documentId: 'doc:1',
+  schemaVersion: 1,
+  changeLimits,
+  onError,
+});
+```
+
+`LocalSync` exposes `state: Readable<LocalSyncState>`, `flush()` and async `dispose()`.
+Only the leader may write while attached. Whole-document replace and externally supplied
+remote apply are unsupported while attached.
+
+`LocalSyncError` is the single public operational error class. Its `code` is one of
+`unavailable`, `schema-mismatch`, `consistency`, `read-only`, `unsupported-operation`,
+`disposed`, `invalid-data`.
+`LocalSyncState` error states carry `LocalSyncError`, and `onError` receives the same
+operational error contract. Consumer state-listener exceptions are isolated from sync
+fault state and `onError`.
+
+`JsonChangeLimits` contains `maxChanges`, `maxBytes`, `maxDepth`, `maxStringLength`.
+`defaultJsonChangeLimits` supplies defaults. Limits admit new local commits only;
+durable replay remains readable under smaller current limits.

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

@@ -0,0 +1,242 @@
+# Public API 参考
+
+这里列出稳定的公开契约。Projection 生命周期和示例见 [Projection 参考](projections.zh-CN.md)，
+建模选择见 [指南](guide.zh-CN.md)。
+
+## Package 入口
+
+| Package            | 用途                                                                  |
+| ------------------ | --------------------------------------------------------------------- |
+| `doxum`            | schema、canonical document runtime、读取、history、impact、projection |
+| `doxum/advanced`   | retained state 与多输出 incremental processor                         |
+| `doxum/react`      | Core capability 的 React adapter                                      |
+| `doxum/local-sync` | IndexedDB 持久化与浏览器 leader/follower 协调                         |
+
+## `doxum`
+
+### Schema
+
+| API                       | 契约                                                  |
+| ------------------------- | ----------------------------------------------------- |
+| `field<T>(validator?)`    | 原子 payload，整体替换；内部只读。                    |
+| `optional(schema)`        | 让 field/variant/map/list/tree member 可缺省。        |
+| `object(shape)`           | 固定声明 member；返回 opaque `ObjectSchema<T>`。      |
+| `variant(tag, variants)`  | object branch 组成的 tagged union。                   |
+| `map(value, { key }?)`    | 动态 keyed record。                                   |
+| `table(entity, { key }?)` | 有序 object/variant entity，数据为 `{ ids, byId }`。  |
+| `list(field, { keyOf })`  | 带稳定 string identity 的有序数组。                   |
+| `tree(field)`             | 空或单根树；optional field 表示 node payload 可缺省。 |
+| `parse(schema, input)`    | 校验 unknown 输入并复制 schema structure。            |
+
+公开 schema 类型包括 `Schema<T>`、`ObjectSchema<T>`、`Infer<S>`、
+`ReadonlyValue<T>`、`Validator<T>`、`SchemaPath<S>`、`PathValueOf<P>`、
+`DocumentAnchor`、`DocumentListConfig<T>`、`DocumentTreeNode<T>`、
+`DocumentTreeValue<T>`。具体 node representation 属于内部实现，不是公开契约。
+`Schema` / `ObjectSchema` 是可跨 package 生成声明的 handle；下游 package 可以直接
+export 推导出的 schema 常量，不需要应用层写 `ReturnType` 包装。
+
+`Validator<T>` 只负责校验。函数 validator 是 predicate/assertion：返回 `true` 或
+`undefined` 表示成功，返回 `false` 表示拒绝，assertion 也可以 throw。
+Standard Schema 成功时必须按 identity 返回原输入；transform output 会被拒绝。
+validator 必须同步且不能修改输入。
+
+Draft collection 方法：
+
+| Container | 读                                           | 写                                                                           |
+| --------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
+| map       | `get`, `has`, `ids`                          | `put`, `remove`, `replace(next)`                                             |
+| table     | `get`, `has`, `ids`                          | `create`, `remove`, `move`, `reorder`, `replace(id,value)`, `replace(next)`  |
+| list      | `get`, `has`, `ids`                          | `insert`, `remove`, `move`, `reorder`, `replace(key,value)`, `replace(next)` |
+| tree      | `rootId`, `get`, `has`, `parent`, `children` | `insert`, `move`, `remove`, `replace(id,value)`, `replace(next)`             |
+
+`replace(parent, key, value)` 用 plain `Infer` 数据替换一个 object/variant member。
+`document.replace(value)` 是 whole-document reset，是独立操作。
+
+### Document runtime
+
+```ts
+const document = createDocument({ schema, initial, history: { capacity: 100 } });
+```
+
+`DocumentRuntime<S>` 提供：
+
+- `schema`、`revision()`、`snapshot()`、`readonly()`；
+- `update(run, { source?, history? }?)`：同步、原子的 Draft mutation；
+- `apply(changes, { expectedRevision, source?: 'local' | 'system', history? })`；remote replay
+  使用 `apply(changes, { expectedRevision, source: 'remote' })`；
+- `replace(value, { source? }?)`：whole-document reset；
+- `subscribe(listener)`、`subscribe(path | paths, listener)`；
+- `history.undo()`、`redo()`、`clear()`、`group()`；
+- `dispose()`。
+
+`document.readonly()` 返回 `ReadonlyDocument<S>`，只保留 `revision()` 和
+document commit/path subscription，用于显式去掉写 capability 的边界。
+
+`update` 返回 `TransactionResult`；`apply`、whole-document `replace`、history travel
+和 group cancel 返回 `OperationResult`。状态为 `committed`、`unchanged`、`rejected`。
+应用层预期拒绝用 `TransactionRejected`；普通 throw 会 rollback 后原样抛出。
+
+Document 错误为 `TransactionRejected`、`DocumentReentrancyError`、
+`DocumentDisposedError`。parse 错误为 `ParseError`，并带 `ParseIssue`。
+
+### 读取与订阅
+
+| API                                     | 契约                                                    |
+| --------------------------------------- | ------------------------------------------------------- |
+| `read(document, selector)`              | 一次同步 borrowed `Read`。                              |
+| `select(document, selector, equality?)` | 动态 read-tracked `Readable<TResult>`。                 |
+| `snapshot(value)`                       | 把 borrowed schema structure 导出为稳定 readonly data。 |
+
+`Readable<T>` 提供 `current()`、`revision()`、`subscribe(listener)`。
+`select` 会随 selector 分支变化重绑依赖；`equality` 判定结果相等时不发布。
+
+Commit 包含 `revision`、`source`、`changes`、`impact`。公开 change/impact 类型包括
+`ChangeSet`、`Change`、`MemberChange`、`ValueTransition`、`DocumentCommit`、
+`DocumentImpact`、`CollectionImpact`、`MutationIssue` 和结果/诊断类型。
+
+### Projection
+
+```ts
+const mode = input<'all' | 'open'>('all');
+const selection = input.collection<RowId, Selection>();
+const rows = observe(document, path => path.rows);
+const count = derive({ rows }, ({ rows }) => rows.size);
+```
+
+| API                                             | 契约                                                                 |
+| ----------------------------------------------- | -------------------------------------------------------------------- |
+| `input(initial, equality?)`                     | Runtime-local writable scalar `Input<T>`。                           |
+| `input.collection<K,V>(initial?, equality?)`    | Runtime-local keyed `CollectionInput<K,V>`，equality 按 entry 比较。 |
+| `observe(document)`                             | whole-document Projection source。                                   |
+| `observe(document, path => ...)`                | schema-path scalar 或 keyed Projection source。                      |
+| `observe(readable)`                             | 接入 Doxum `Readable`。                                              |
+| `observe(externalSource)`                       | 接入公开 external value/collection source contract。                 |
+| `derive(dependencies, compute, equality?)`      | named dependencies 的 pure value Projection。                        |
+| `derive.keyed(driver, select, equality?)`       | 保留 driver key/order，逐 entry projection。                         |
+| `derive.keyed(driver, deps, select, equality?)` | 带 named global/dynamic keyed dependencies 的 keyed projection。     |
+
+动态 keyed dependency 写法为
+`{ source: keyedProjection, key: (driverValue, driverKey) => sourceKey | undefined }`。
+Runtime 拥有 output-key → source-key binding 和 reverse invalidation。这个 helper shape
+在调用点自动推断，不暴露独立 public helper type。
+keyed selector 的前置参数固定：无额外 dependency 时为 `(value, key)`；存在 named
+dependency object 时为 `(value, key, dependencies)`。
+
+`ProjectionRuntime` 提供：
+
+- `read(projection)`；
+- `select(projection)`、`select(projection, selector, equality?)`；
+- `update(input, nextValue)`：写 scalar `Input<T>`；
+- `update(collectionInput, draft => ...)`：写 `CollectionInput<K,V>`；
+- `batch(run, { cause? }?)`；
+- `scope()`；
+- `dispose()`。
+
+`input.collection` 的 draft callback 与逐 entry equality 都在本地状态正式安装前完成；
+任一环节抛错时，已发布 collection 与下一次 draft 都保持更新前状态。
+
+`CollectionInputDraft` 提供 `get`、`has`、`set`、`remove`。edit callback throw 时该次 edit
+整体不应用。`ProjectionScope` 镜像 `read`、`select`、`update`、`batch`、`dispose`，
+并增加 `own(projectionOrTree)`，统一拥有 scalar/keyed input、derive 与 advanced output
+tree 的 lifecycle。同一个 definition 只能属于一个 scope，并且必须在该 definition
+首次作为 root materialize 之前调用 `own`。
+
+公开 Projection 类型包括 `Projection<T>`、`KeyedProjection<K,V>`、`Input<T>`、
+`CollectionInput<K,V>`、`CollectionInputDraft<K,V>`、`ProjectionRuntime`、
+`ProjectionScope` 和 external source/event contract。所有 keyed producer 都返回
+`KeyedProjection<K,V>`；`CollectionInput<K,V>` 是它的 Runtime-local writable 形式。
+`ProjectionError` 只公开 `phase` 与 `cause`；
+`ProjectionDisposedError` 表达 disposed access。
+
+External value source 提供 `kind: 'value'`、`current()`、`revision()`、`subscribe()`。
+External collection source 提供 `kind: 'collection'` 和 `get/has/ids` read，可给
+`CollectionImpact` invalidation hint；adapter 会导出精确 `CollectionChange`。
+
+## `doxum/advanced`
+
+只有 retained state、cross-key index 或直接 incremental patch 无法用
+`derive` / `derive.keyed` 清晰表达时才使用 advanced processor。
+
+所有 advanced API 都使用 named dependencies + closed definition object。
+
+```ts
+const total = incremental(
+  { rows },
+  {
+    state: () => ({ runs: 0 }),
+    process: ({ values, changes, previous, reset, cause, state }) => nextValue,
+  }
+);
+```
+
+`incremental.collection(dependencies, { process, state? })` 额外提供 keyed
+`previous`、`next` 和 borrowed `output`；output 有 `set`、`remove`、`order`。只有确实
+需要 retained state 时才声明 `state()`；无状态 process context 不包含 `state`。
+
+`incremental.group(dependencies, { output, process, state? })` 声明多个 leaf：
+
+```ts
+const view = incremental.group(
+  { rows },
+  {
+    output: define => ({
+      cards: define.collection<RowId, Card>(),
+      count: define.value<number>(),
+    }),
+    state: () => ({ runs: 0 }),
+    process: ({ values, changes, previous, next, output, reset, cause, state }) => {},
+  }
+);
+```
+
+`define.collection<K,V>(equality?)`、`define.value<T>(equality?)` 只存在于
+`output` callback 内。返回值必须是非空静态 object tree，每个 descriptor 恰好返回一次；
+最终同 shape 的 collection leaf 是 `KeyedProjection<K,V>`，value leaf 是
+`Projection<T>`。
+
+普通 source reset 保留已声明的 retained state。processor fault 的 recovery 由 Runtime
+拥有：重新创建已声明的 state，再执行 reset evaluation；stateless processor 走同一恢复
+路径但没有 state object。没有公开 rebuild token 或手工恢复协议。
+
+advanced 导出 value/collection/group 的 context/definition 类型、`CollectionChange`，
+以及声明可移植性所需的 `IncrementalGroupOutput` / `IncrementalGroupResult` 类型边界。
+普通调用方通常只依赖推导；scheduler/output runtime plumbing 不属于公开 API。
+
+## `doxum/react`
+
+| API                                                  | 契约                                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------- |
+| `ProjectionProvider`                                 | 提供 `ProjectionRuntime` 或 `ProjectionScope`。               |
+| `useProjection(projection)`                          | 读取 Projection。                                             |
+| `useProjection(projection, selector, equality?)`     | selector 形式读取 Projection。                                |
+| `useInput(input)`                                    | scalar `[value,setValue]` 或 collection `[map,updateDraft]`。 |
+| `useDocumentSelector(document, selector, equality?)` | Core document `select` 的 React adapter。                     |
+| `useReadable(readable)`                              | 订阅任意 Doxum `Readable`。                                   |
+| `useHistory(history)`                                | history state + `undo` / `redo`。                             |
+
+## `doxum/local-sync`
+
+```ts
+const sync = await attachLocalSync({
+  runtime: document,
+  database: 'app',
+  documentId: 'doc:1',
+  schemaVersion: 1,
+  changeLimits,
+  onError,
+});
+```
+
+`LocalSync` 提供 `state: Readable<LocalSyncState>`、`flush()`、async `dispose()`。
+attached 时只有 leader 可写；whole-document replace 和外部 remote apply 不支持。
+
+`LocalSyncError` 是唯一公开 operational error class。`code` 取值：
+`unavailable`、`schema-mismatch`、`consistency`、`read-only`、
+`unsupported-operation`、`disposed`、`invalid-data`。
+`LocalSyncState` 的 error state 持有 `LocalSyncError`，`onError` 也只接收同一
+operational error contract；consumer state-listener exception 不进入 sync fault state
+或 `onError`。
+
+`JsonChangeLimits` 包含 `maxChanges`、`maxBytes`、`maxDepth`、`maxStringLength`。
+`defaultJsonChangeLimits` 提供默认值。limits 只限制新 local commit；更小的新 limit
+不会阻止读取已经持久化的 durable replay。

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

@@ -1,5 +1,9 @@
 # Doxum Guide
 
+For exact signatures across `doxum`, `doxum/advanced`, `doxum/react`, and
+`doxum/local-sync`, use the [API reference](api.en.md). This guide focuses on choices
+and lifecycle semantics.
+
 ## Define, Update And Read
 
 ```ts
@@ -16,7 +20,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));
@@ -70,9 +73,10 @@ Trees may be empty. `tree(field(...))` requires an own `value` on every existing
 node; `tree(optional(field(...)))` explicitly permits missing node payloads, while
 `optional(tree(...))` independently permits the whole tree member to be absent.
 
-Pure synchronous functions and Standard Schema v1 validators receive original input.
-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
+Function validators are synchronous predicates/assertions: `true` or `undefined`
+succeeds, `false` rejects, and assertions may throw. Standard Schema v1 validators
+must return the original input by identity; transformed output is rejected. Validators
+must not mutate input. 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 methods, symbolic paths and impact.
 Path callbacks describe locations, including absent entries, and compile at registration.
@@ -96,10 +100,16 @@ reversible root reset; remote commits invalidate local history. Observer errors
 after acceptance.
 
 Use `observe(document, path => path.tasks)` for a collection boundary and
-`derive([tasks, filter], (tasks, filter) => ...)` for pure values. Definitions are
-lazy and materialized by one `createProjectionRuntime({ onError })` owner. Sources
-remain explicit. Retained state, reverse indexes and keyed output patches belong to
-the isolated `doxum/advanced` incremental entry points. See the [projection
+`derive({ tasks, filter }, ({ tasks, filter }) => ...)` for pure values. Definitions are
+lazy and materialized by one `createProjectionRuntime({ onError })` owner. When a
+keyed source determines output keys/order, map entries independently with
+`derive.keyed(entries, entry => entry.label)`. Dynamic keyed lookup stays in that
+same derivation through a named dependency object; plain Projection members are
+global dependencies and `{ source, key }` members are per-output-key lookups. The
+selector receives `(entry, key, dependencies)`, while the Runtime owns the
+binding/reverse index and the producer DAG remains explicit. Use isolated
+`doxum/advanced` incremental entry points only for retained state, custom cross-key
+indexes or keyed patches that `derive.keyed` cannot express. See the [projection
 reference](projections.en.md) for lifecycle, draft semantics, selector tracking,
 batching and recovery.
 Tree structure uses the same projection source protocols: observe `path.tree.rootId`