doxum 0.1.7 → 0.1.9

package/README.md

@@ -1,327 +1,245 @@
 # Doxum
 
-Doxum is a typed TypeScript runtime for complex mutable documents. It is built
-for editors and product surfaces that need structured state, atomic updates,
-undo/redo, precise change notifications, and incremental derived data.
-
-Licensed under the [MIT License](LICENSE).
-
-The `doxum` core entry is a local in-memory runtime. The optional
-`doxum/local-sync` browser attachment adds IndexedDB persistence and
-same-origin cross-tab synchronization with one writable tab at a time; network
-collaboration, authorization, and conflict resolution remain separate
-application concerns.
-
-## Packages
-
-- `doxum` defines schemas, mutations, history, subscriptions, and views.
-- `doxum/local-sync` lets one Web-Lock leader write a runtime synchronously,
-  persists its commands asynchronously to IndexedDB, and makes other tabs
-  ordered read-only mirrors.
-- `doxum/react` binds Doxum read models to React 18+ with fine-grained external
-  store subscriptions.
-
-## Install
+Doxum is a TypeScript runtime for mutable documents with synchronous atomic
+updates, reversible final changes, history, precise subscriptions, and incremental
+projections. Licensed under the [MIT License](LICENSE).
 
 ```sh
 pnpm add doxum
 ```
 
-For React bindings, install React alongside Doxum and import from `doxum/react`:
-
-```sh
-pnpm add doxum react
-```
-
-Use the package manager that owns your application if it is not pnpm.
-
-## AI Development Guide
-
-Doxum ships a task-oriented guide for AI assistants and application developers.
-It is the recommended reference for using `doxum` and `doxum/react` in place
-of a generated, symbol-by-symbol API reference. The guide is included in the
-published `doxum` package at `skills/doxum-runtime`.
-
-- [English guide](skills/doxum-runtime/references/guide.en.md)
-- [中文指南](skills/doxum-runtime/references/guide.zh-CN.md)
-- [English patterns](skills/doxum-runtime/references/patterns.en.md)
-- [中文模式参考](skills/doxum-runtime/references/patterns.zh-CN.md)
-- [English invariants](skills/doxum-runtime/references/invariants.en.md)
-- [中文不变量](skills/doxum-runtime/references/invariants.zh-CN.md)
-- [AI skill instructions](skills/doxum-runtime/SKILL.md)
-
-Tools that support `SKILL.md` can install or link the complete
-`doxum-runtime` directory as the `$doxum-runtime` skill. The files are also
-ordinary Markdown: read the guide matching your working language, then use the
-patterns and invariants references for the task at hand.
-
-## Quick Start
-
-Define the document shape once. Doxum infers the immutable document value and
-the reader and writer APIs from that schema.
+## Define And Update
 
 ```ts
-import { createDocument, field, object, schema, table } from 'doxum';
-
-const task = object({
-  title: field<string>(),
-  completed: field<boolean>(),
-});
+import { createDocument, field, map, object, type Infer } from 'doxum';
 
-const taskSchema = schema({
-  title: field<string>(),
-  tasks: table(task),
-});
+const task = object({ title: field<string>(), done: field<boolean>() });
+const model = object({ tasks: map(task), title: field<string>() });
+type TaskDocument = Infer<typeof model>;
 
-const runtime = createDocument({
-  schema: taskSchema,
-  initial: {
-    title: 'Launch',
-    tasks: {
-      ids: ['task-1'],
-      byId: {
-        'task-1': { title: 'Write the brief', completed: false },
-      },
-    },
-  },
+const document = createDocument({
+  schema: model,
+  initial: { title: 'Launch', tasks: { a: { title: 'Write', done: false } } },
 });
 
-runtime.update(tx => {
-  tx.write.tasks.item('task-1').completed.set(true);
-  return tx.read.tasks.get('task-1')?.title.get();
+document.update(draft => {
+  const task = draft.tasks.a;
+  if (task) task.done = true;
+  draft.tasks.b = { title: 'Review', done: false };
+  delete draft.tasks.a;
+  return { warnings: [] };
 });
 ```
 
-An update is synchronous and atomic. `apply` decodes untrusted operation
-payloads before they reach mutation code. A malformed or semantically rejected
-operation returns a typed `MutationIssue`; if an operation is rejected, if the
-transaction calls `tx.reject`, or if user code throws, every preceding change
-in that update is rolled back.
+The root object is the schema identity. Multiple runtimes can share its definition;
+their data, revisions and subscriptions remain independent. Definitions are immutable.
+
+`object()` exposes editable structure with a closed schema: undeclared own properties,
+including symbols and non-enumerable properties, are rejected at input boundaries.
+A variant allows its discriminant and the active branch's declared members.
+Use `map()` for dynamic keys and `field<T>()` for arbitrary payload objects.
+`field<T>()` is atomic: replace the whole
+value, including objects, arrays, Maps and Dates. Atomic payloads are shared by
+reference across inputs, reads, snapshots, commits and history. They are deeply
+readonly in `Infer`/`Read`/`Draft`: never mutate them through any alias, even after
+removal from the document. Published results are readonly by contract, without
+defensive deep copying or runtime freezing. Classes and functions need no copier.
+
+Drafts and structural reads are borrowed for their synchronous callback. Draft and
+internal reader proxies must not escape their callback; escaping them is undefined
+behavior. Ordinary property
+reads see preceding writes in the same update. Same-address proxies are stable
+within a scope and resolve against current structure after replacement.
+
+Throw `new TransactionRejected({ code, message, address? })` for expected business
+rejection. Schema and structural failures also return `status: 'rejected'` and
+restore all prior work. Other thrown values roll back and are rethrown unchanged.
+Normal callback returns, including `false`, are business results, not cancellation.
+Committed observer failures are returned in `observerErrors` without rollback.
+
+## Read And Observe
 
-Mutation failure codes are a closed public `MutationIssueCode` union. For
-application validation, use `tx.report` or `tx.reject` with a
-diagnostic `{ code, message, address? }`; Doxum adds `source: 'application'`.
-Published diagnostic arrays and addresses are copied and frozen.
+```ts
+import { select, snapshot } from 'doxum';
+
+const title = select(document, state => state.title);
+const tasks = select(document, state => snapshot(state.tasks));
+document.subscribe(
+  path => path.tasks.item('b').title,
+  commit => {
+    console.log(commit.revision, commit.changes);
+  }
+);
+document.subscribe([path => path.title, path => path.tasks], () => {});
+```
 
-## Read And Subscribe
+`snapshot` exports a stable value with the subtree's `Infer` type: editable schema
+structure is copied, while immutable atomic payloads keep their identity.
+`snapshot(rawPayload)` returns that same readonly reference. To edit exported
+payloads, explicitly copy them in application code; `structuredClone` works for
+supported types, while classes/functions need application-specific handling.
+Use ordinary properties for fine-grained reads. Data callbacks read real values;
+path callbacks describe symbolic schema locations, including missing entries.
+Subscription paths compile once during registration.
 
-Use `select` for a one-off typed read. Use schema selectors and `subscribe`
-when a non-React consumer needs only relevant commits.
+React integration:
 
 ```ts
-import { select } from 'doxum';
+import { useDocumentSelector, useHistory, useReadable } from 'doxum/react';
 
-const taskTitles = select(runtime, read =>
-  read.tasks.ids().map(id => read.tasks.get(id)?.title.get())
-);
-
-const tasks = taskSchema.collection(path => path.tasks);
-const stop = runtime.subscribe(tasks, commit => {
-  const change = commit.impact.collection(tasks);
-  if (change.kind === 'incremental') console.log(change.updated);
-});
-
-stop();
+const title = useDocumentSelector(document, state => state.title);
+const history = useHistory(document.history);
 ```
 
-Each committed update produces a revision, forward operations, inverse
-operations, and a `DocumentImpact`. Collection impacts distinguish added,
-removed, updated, and reordered entries.
-
-## History And Operations
+React tracks fields actually read and updates dependencies when the selector
+branches. The core has no React dependency. `asReadable(document)` removes write
+capabilities while retaining selection, subscription and projection support.
 
-Local history is enabled by default with a capacity of 100 commits. Doxum
-records inverse operations, so undo and redo follow the same mutation path as
-ordinary updates.
+## Containers And Parsing
 
-```ts
-runtime.history.undo();
-runtime.history.redo();
+- `map(field(...))`, `map(object(...))`, `map(variant(...))` use key indexing,
+  assignment and deletion. Absent differs from present `undefined`.
+- `table(object(...))` retains `{ ids, byId }` data and `get/has/ids/create/remove/move`.
+- `list(field(...), { keyOf })` retains a plain array and `get/has/ids/insert/set/remove/move/replace`.
+- `tree(field(...))` retains `{ rootId?, nodes }` and explicit topology methods.
+- `variant(tag, branches)` has a readonly discriminant and whole-value branch replacement.
+- `optional(node)` permits absence for fields, variants, maps, lists and trees.
 
-runtime.apply([{ type: 'field.set', at: ['title'], value: 'Ship Doxum' }]);
-```
+Map/table key validators preserve branded string types through access, paths,
+projection keys and impact queries. Validators are pure, synchronous functions or
+Standard Schema v1 validators. They receive the original value, must not mutate it,
+and their successful output is ignored. Perform transformations before calling
+Doxum; it does not detect validator mutation or conversion. `parse(model, unknown)`
+validates and copies schema structure while sharing readonly payloads. Strict parsing
+requires validators for atomic fields; typed in-memory fields can omit them.
 
-Use `runtime.history.group()` for one action spanning multiple synchronous
-updates, such as a drag. Keep its handle until the action ends, then call
-`end()` to retain one undo entry or `cancel()` to apply its inverses atomically.
-Groups cannot nest. Undo, redo, clear, remote/replace commits, and committed
-updates with `history: false` end the current group. History implements
-`Readable<HistoryState>` and can be used with `useReadable` or `fromReadable`.
-
-`apply` is the boundary for replaying operations from persistence or a network
-adapter. Doxum does not provide those adapters. A `replace` or a commit marked
-as `remote` invalidates local history because its prior inverse sequence is no
-longer authoritative.
-
-The returned result distinguishes `committed`, `unchanged`, and `rejected`.
-Observer failures do not turn a completed write into a rejection: committed
-results expose them in `observerErrors`, after history and canonical state have
-already settled.
-
-## Local Persistence And Cross-Tab Sync
-
-`doxum/local-sync` is an optional browser attachment for a document that needs
-offline persistence and same-origin, cross-tab convergence. It uses IndexedDB
-as the ordered checkpoint and commit log, Web Locks to serialize background
-confirmation, and BroadcastChannel only to notify other tabs to catch up from
-IndexedDB. It does not need a server or Yjs.
-
-The attachment deliberately uses a simple single-writer model. It hydrates the
-runtime from the IndexedDB checkpoint and ordered command log, then attempts to
-hold a Web Lock for that document. The lock holder is the `leader` and may use
-the normal synchronous runtime APIs. All other attached tabs are `follower`
-mirrors: they read the durable tail in order after a BroadcastChannel hint, and
-their direct writes throw `LocalSyncReadOnlyError`. When the leader disposes,
-a follower catches up and becomes the next leader.
-
-The leader's `runtime.update`, normal `runtime.apply`, and
-`runtime.history.undo()` / `redo()` stay synchronous and immediately visible.
-Local-sync observes the resulting local, system, and history commits and writes
-their JSON operation batches to IndexedDB in the background. It deliberately
-rejects `runtime.replace()` and an externally supplied `apply(..., {
-source: 'remote' })` while attached: neither is a local operation command that
-the log can faithfully append. `flush()` is the explicit point that waits for
-commits observed before the call to persist (or, in a follower, waits to catch
-up to the durable head). A browser crash, quota failure, or malformed JSON
-payload can therefore leave an already visible leader commit unpersisted;
-observe `state` or use `onError` to surface that condition.
+For replacements containing nested collection tools, use `assign(scope, key, value)`:
 
 ```ts
-import { createDocument, select } from 'doxum';
-import { attachLocalSync } from 'doxum/local-sync';
-
-const runtime = createDocument({
-  schema: taskSchema,
-  initial: {
-    title: 'Launch',
-    tasks: { ids: [], byId: {} },
-  },
-});
-
-const localSync = await attachLocalSync({
-  runtime,
-  database: 'my-app',
-  documentId: 'project-1',
+import { assign, table } from 'doxum';
+const boardModel = object({ entries: map(object({ rows: table(task) })) });
+const board = createDocument({ schema: boardModel, initial: { entries: {} } });
+board.update(draft => {
+  assign(draft.entries, 'a', { rows: { ids: [], byId: {} } });
 });
+```
 
-if (localSync.state.current().status === 'leader') {
-  runtime.update(tx => {
-    tx.write.title.set('Ship Doxum');
-  });
+TypeScript cannot give a mapped property a draft read type and a different plain
+data assignment type. `assign` checks the key and its `Infer` value and calls the
+same transaction write path. It is useful for complex map entries, variant
+replacement and initializing optional lists/trees. Ordinary assignments remain
+the common case. See [value boundaries](docs/value-boundaries.md).
 
-  runtime.history.undo();
-}
+## Changes And History
 
-select(runtime, read => read.title.get()); // leader write or follower replay
-await localSync.flush(); // persist observed leader commands / catch up a follower
+A commit contains `{ revision, source, changes, impact }`. Repeated writes to one
+field produce one first-before/final-after fact. Net-zero transactions do not
+advance revision or notify. A `members` change shares its container address across
+member transitions: `added` carries `after`, `removed` carries `before`, and
+`updated` carries both. `order` records key sequences, `tree` records touched nodes
+and nullable root IDs, and `reset` records a whole-document transition. There are
+no per-value presence wrappers or intermediate assignment logs.
 
-await localSync.dispose();
+```ts
+const changes = {
+  changes: [
+    {
+      kind: 'members',
+      at: ['tasks', 'a'],
+      members: [{ key: 'title', kind: 'updated', before: 'A', after: 'B' }],
+    },
+  ],
+};
 ```
 
-`localSync.state` is a `Readable`: `state.current()` returns a stable snapshot,
-`state.subscribe(listener)` observes persistence, leadership and error changes,
-and React can consume it with `useReadable(localSync.state)`.
+Each container appears in at most one members group. Grouping preserves exact
+field impact; a group at `[]` is an incremental root-member change, not a reset.
+An ordered container's group may also contain `order: { before, after }` with its
+complete key sequences. Order-only groups use `members: []`; a standalone `order`
+change or a second group for the same container is rejected. Apply installs each
+group's members and order together before moving to the next group.
 
-`attachLocalSync` first hydrates the passed runtime from IndexedDB; await it
-before allowing reads or edits. It does not make runtime mutation asynchronous,
-does not own `runtime.dispose()`, and does not expose a second undo API. Runtime
-history is in-memory only: hydration and remote tail application invalidate it,
-so an undo stack never transfers to a new leader or survives reopening a tab.
-Local-sync data must be JSON. Because command validation happens after the
-runtime commit, a non-JSON payload is reported as a post-commit attachment error
-rather than rolling back an already observed document change.
+`document.apply(changes, { expectedRevision })` accepts unknown input. The revision
+must match this runtime. The decoder rejects malformed and overlapping facts, then
+the same session applies the complete transition atomically. Received `before`
+values support reverse replay but are not trusted as local undo data; the runtime
+captures its actual old state. Revision is a local baseline, not a distributed
+conflict-resolution protocol.
 
-## React
+Published ChangeSets are readonly in their entirety, including envelope objects,
+addresses, transitions and order arrays. The runtime reuses validation of its own
+publications and normalized storage input by identity; fresh unknown input still
+passes through the decoder and every apply validates against current local state.
 
-`useDocumentSelector` learns the paths read by its selector and re-renders only
-when a matching commit changes the selected result.
+`history.undo()` and `redo()` replay the same changes by direction. A history group
+holds complete commits and travels atomically with one notification:
 
-```tsx
-import { useDocumentSelector } from 'doxum/react';
-
-function TaskCount() {
-  const count = useDocumentSelector(runtime, read => read.tasks.ids().length);
-  return <output>{count}</output>;
-}
+```ts
+const group = document.history.group();
+document.update(draft => {
+  draft.title = 'First';
+});
+document.update(draft => {
+  draft.title = 'Final';
+});
+group.end();
+document.history.undo();
 ```
 
-Use `useReadable` and `useHistory` with Doxum collection
-views, materialized views, and history state.
-
-## Derived Views
+`group.cancel()` restores its start and pre-group history. Local `replace` is an
+explicit reversible root reset. Remote commits invalidate local history. Writes
+with `history: false` close the active group.
 
-`createProjectionRuntime` owns an explicit graph of derived values and keyed
-collections. It combines document runtimes and external values without owning
-their mutations or history.
+## Projections
 
 ```ts
-const projection = createProjectionRuntime({ onError: error => console.error(error) });
-const document = projection.document(runtime);
-const taskTitles = projection.map(
-  document.collection(path => path.tasks),
-  (_id, task) => task.title.get()
+import { createProjectionStore, input, project } from 'doxum';
+
+const titles = project(
+  document,
+  path => path.tasks,
+  (id, task) => `${id}: ${task.title}`
 );
-const taskCount = projection.value({ tasks: taskTitles }, ({ tasks }) => tasks.ids().length);
-const labels = projection.map(taskTitles, (id, title) => `${id}: ${title}`);
+const count = project({ titles }, ({ titles }) => titles.ids().length);
+const zoom = input(1);
+const scaled = project({ count, zoom }, ({ count, zoom }) => count * zoom);
+
+const store = createProjectionStore({ onError: console.error });
+store.get(scaled);
+store.set(zoom, 2);
 ```
 
-`projection.value(sources, compute, { isEqual }?)` is the ordinary pure-compute
-entry. Stateful algorithms use `projection.value({ sources, build }, { isEqual }?)`,
-where build returns `{ value, update }`. Both use the same scheduler and lifecycle.
-
-`projection.collection<Item>()(spec)` handles custom incremental algorithms. Its scoped
-writer supports `set`, `remove`, `order`, and `replace`; `previous` and `next`
-provide scoped reads. Declare all sources and use their native commit impacts
-or upstream collection changes to choose candidate keys. A document collection
-context also provides `candidates.keys`, `candidates.orderDirty` and `reset`,
-aggregated across the entire batch. Candidates include net-zero changes; read
-final state to decide the output. Doxum stages writes,
-applies equality, and publishes exact `CollectionImpact` changes. It does not
-automatically track item dependencies. `ids`, lazy `all`, and cached `item(id)`
-implement `Readable` and work with `useReadable`.
-
-`map` accepts document collections and upstream projection collections while
-preserving keys and order. Source dependencies stay explicit.
-
-Use `projection.input(initial, { isEqual })` for boundary values such as container
-size. Its application-owned `set` updates a read-only `source`. Use
-`projection.fromReadable(existing, { isEqual })` for an existing external source.
-Neither replaces a document with domain mutation semantics.
-
-Wrap the entire synchronous application action in `projection.batch(() => ...)`
-before its first document commit to combine document changes and editor cleanup.
-Batches nest, preserve committed source changes on exceptions, and provide no
-cross-document rollback. Projection reads inside a batch return the last
-published state. Document listeners still run synchronously.
-
-All affected nodes settle before listeners. Output revisions change only when
-their output changes. Update failures discard the processor instance and attempt
-one fresh build; persistent faults block descendants, while independent branches
-continue. Errors reach `onError` and, when inside document notification, the
-committed result's `observerErrors`. Manual `rebuild()` uses the same graph.
-Dispose the projection with its service; component unmount only unsubscribes.
-Disposing a node with consumers is rejected, and disposed handles throw.
-
-Schema access uses `object` for structured entities and `dict` for keyed values.
-Variants expose `reader.get()` as a discriminated union and `writer.replace()`
-for replacement. Optional presence is supported by field, variant, dict, list
-and tree nodes. Dictionaries expose `get(key)`, `has(key)`, `keys()` and
-`values()`; lists additionally support `get(key)` and `has(key)` using `keyOf`.
-Tree insert/move accept `{ parentId, index }`, with index denoting the final
-position after removing a moved node. See [API migration](docs/api-migration.md)
-for breaking changes and the public surface.
-
-## Data Ownership
-
-Doxum clones the initial document. Structural values supplied through operations
-are transferred to its mutable canonical document, while published commit and
-history payloads are immutable snapshots. Treat data passed to an update as
-owned by Doxum after the call unless the value is intentionally immutable.
-
-Tree replacement snapshots are an exception: Doxum validates and clones the
-tree structure so a caller cannot later corrupt its single-root, connected,
-acyclic representation. Tree insert and move operations preserve the same
-invariant.
+Projection declarations are lazy and reusable. A `ProjectionStore` owns
+materialized values, subscriptions, batching, processor state and disposal.
+`project(document, path)` binds a document collection; adding a mapper performs
+incremental keyed mapping. `project(readable)` bridges an external readable.
+Pure computations receive current values. Advanced processors use tagged specs:
+`project({ kind: 'value', sources, build })` and
+`project({ kind: 'collection', sources, build })`.
+Document collection events provide scoped `read.get/has/ids`, final candidate
+keys, order dirtiness, commits and reset state.
+
+Processors settle before external listeners. `store.batch` defers graph
+settlement and projection notifications, but document commits/listeners remain
+synchronous. Projection readers inside the batch see the last publication.
+Dispose projection stores with their owning service.
+See [projection contracts](docs/projections.md).
+
+## Local Sync
+
+`doxum/local-sync` attaches an IndexedDB timeline and Web Lock leadership to a
+runtime. One leader writes synchronously and persists final changes asynchronously;
+followers apply the durable sequence in order. `flush()` waits for persistence.
+Durability errors do not roll back an already visible commit.
+
+The storage format is IndexedDB version 5 with format version 3 records. Earlier
+databases are rejected without upgrading, deleting or converting their data.
+This JSON adapter rejects non-JSON atomic values. Network collaboration and
+collaborative undo remain separate concerns; see [collaboration design](COLLABORATION_DESIGN.md).
+Change count limits count individual members and tree nodes, not just outer groups.
+`changeLimits` applies to newly authored local commits. Previously persisted
+commits remain readable by followers and after reopening with smaller limits;
+their JSON and ChangeSet structure are still validated.
 
 ## Development
 
@@ -331,29 +249,32 @@ pnpm run check
 pnpm run build
 pnpm run bench
 pnpm run profile
+node test.mjs
+node core/bench/architecture.mjs --isolate
 ```
 
-See [the architecture guide](docs/architecture.md) for the runtime pipeline and
-[AGENTS.md](AGENTS.md) for contribution rules.
+The architecture benchmark isolates each workload in a fresh process. Use
+`--allocation` for separate V8 allocation sampling, `DOXUM_BENCH_FILTER` for a
+comma-separated workload list, and `DOXUM_BENCH_MODULE=/absolute/path/to/index.js`
+to compare a saved build. Sampling timings are not normal latency measurements.
+`pnpm run profile` reports work counters and separates writes, sealing, remaining
+runtime/publication work and explicit impact queries.
+It also reports structural generation advances and distinguishes captured order
+baselines from final published order copies. Architecture workloads include order
+round trips and repeated tree edits to expose costs hidden by commit-only benchmarks.
+
+Builds produce root `dist` ESM/CJS/declarations for `doxum`, `doxum/integration`,
+`doxum/local-sync` and `doxum/react`. Source ownership is described in
+[architecture](docs/architecture.md) and [AGENTS.md](AGENTS.md).
+The runtime shares one transaction lifecycle; complete mutation operations are
+organized by domain under `core/src/mutation/operations`, with access, first-touch
+recording and publication retaining their own responsibilities.
+The published [runtime skill](skills/doxum-runtime/SKILL.md) includes English and
+Chinese application guidance.
 
 ## Release
 
-`doxum` is released as one package. A normal release always increments the
-patch version:
-
-```sh
-pnpm release
-```
-
-Run it only from a clean, synchronized `main` branch. The command verifies the
-logged-in npm account, updates both public package versions, runs the complete
-check and build, verifies the publish tarball, publishes the package, then
-creates and pushes a `vX.Y.Z` release commit and tag.
-
-If npm accepts one package but the command cannot finish, it preserves the
-release state rather than reverting a version that may already be public. Fix
-the external failure and continue with:
-
-```sh
-pnpm release:resume
-```
+Run `pnpm release` from a clean, synchronized `main` branch to execute the release
+checks, build, tarball validation, npm publication and release commit/tag steps.
+Use `pnpm release:resume` to continue an interrupted release after resolving its
+external failure. Publication is a separate maintainer action.