doxum 0.1.5 → 0.1.7

package/README.md

@@ -100,8 +100,8 @@ in that update is rolled back.
 
 Mutation failure codes are a closed public `MutationIssueCode` union. For
 application validation, use `tx.report` or `tx.reject` with a
-`DocumentDiagnostic`; published diagnostic arrays and addresses are copied and
-frozen.
+diagnostic `{ code, message, address? }`; Doxum adds `source: 'application'`.
+Published diagnostic arrays and addresses are copied and frozen.
 
 ## Read And Subscribe
 
@@ -141,6 +141,13 @@ runtime.history.redo();
 runtime.apply([{ type: 'field.set', at: ['title'], value: 'Ship Doxum' }]);
 ```
 
+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
@@ -177,7 +184,7 @@ 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;
-inspect `state()` or use `onError` to surface that condition.
+observe `state` or use `onError` to surface that condition.
 
 ```ts
 import { createDocument, select } from 'doxum';
@@ -197,7 +204,7 @@ const localSync = await attachLocalSync({
   documentId: 'project-1',
 });
 
-if (localSync.state().status === 'leader') {
+if (localSync.state.current().status === 'leader') {
   runtime.update(tx => {
     tx.write.title.set('Ship Doxum');
   });
@@ -211,6 +218,10 @@ await localSync.flush(); // persist observed leader commands / catch up a follow
 await localSync.dispose();
 ```
 
+`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)`.
+
 `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
@@ -239,11 +250,66 @@ views, materialized views, and history state.
 
 ## Derived Views
 
-`createCollectionView` incrementally projects one table or map into `ids`,
-`all`, and cached `item(id)` readables. `createMaterializedView` is for
-indexes and aggregates that need custom incremental update logic. A materialized
-view may depend on earlier views from the same runtime; Doxum settles that graph
-before notifying external listeners.
+`createProjectionRuntime` owns an explicit graph of derived values and keyed
+collections. It combines document runtimes and external values without owning
+their mutations or history.
+
+```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()
+);
+const taskCount = projection.value({ tasks: taskTitles }, ({ tasks }) => tasks.ids().length);
+const labels = projection.map(taskTitles, (id, title) => `${id}: ${title}`);
+```
+
+`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
 

package/dist/{contract-4E3moCbY.d.ts → contract-DNZ4D53r.d.ts}

@@ -40,19 +40,12 @@ type VariantNode<TTag extends string, TVariants extends VariantShape> = BaseNode
   readonly tag: TTag;
   readonly variants: TVariants;
 };
-type SingleNode<TValue extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = BaseNode<'single'> & {
-  readonly value: TValue;
-};
 type TableNode<TValue extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = BaseNode<'table'> & {
   readonly value: TValue;
 };
 type MapNode<TValue extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = BaseNode<'map'> & {
   readonly value: TValue;
 };
-type RecordNode<TId extends string, TValue> = BaseNode<'record'> & {
-  readonly __id?: TId;
-  readonly __value?: TValue;
-};
 type DictNode<TKey extends string, TValue> = BaseNode<'dict'> & {
   readonly __key?: TKey;
   readonly __value?: TValue;
@@ -64,12 +57,12 @@ type ListNode<TItem> = BaseNode<'list'> & {
 type TreeNode<TValue> = BaseNode<'tree'> & {
   readonly __value?: TValue;
 };
-type DocumentNode = FieldNode<unknown, false> | FieldNode<unknown, true> | ObjectNode<ObjectShape> | VariantNode<string, VariantShape> | SingleNode<ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> | TableNode<ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> | MapNode<ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> | RecordNode<string, unknown> | DictNode<string, unknown> | ListNode<unknown> | TreeNode<unknown>;
+type DocumentNode = FieldNode<unknown, false> | FieldNode<unknown, true> | ObjectNode<ObjectShape> | VariantNode<string, VariantShape> | TableNode<ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> | MapNode<ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> | DictNode<string, unknown> | ListNode<unknown> | TreeNode<unknown>;
 type EntityValue<N extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = N extends ObjectNode<infer S> ? DocumentValueOfShape<S> : N extends VariantNode<infer T, infer V> ? { [K in keyof V & string]: { [P in T]: K } & DocumentValueOfShape<V[K] extends ObjectNode<infer S> ? S : never> }[keyof V & string] : never;
-type DocumentValueOfNode<N> = N extends FieldNode<infer T, infer O> ? O extends true ? T | undefined : T : N extends ObjectNode<infer S> ? DocumentValueOfShape<S> : N extends VariantNode<infer T, infer V> ? EntityValue<VariantNode<T, V>> : N extends SingleNode<infer V> ? EntityValue<V> : N extends TableNode<infer V> ? {
+type DocumentValueOfNode<N> = N extends FieldNode<infer T, infer O> ? O extends true ? T | undefined : T : N extends ObjectNode<infer S> ? DocumentValueOfShape<S> : N extends VariantNode<infer T, infer V> ? EntityValue<VariantNode<T, V>> : N extends TableNode<infer V> ? {
   readonly ids: readonly string[];
   readonly byId: Readonly<Record<string, EntityValue<V>>>;
-} : N extends MapNode<infer V> ? Readonly<Record<string, EntityValue<V>>> : N extends RecordNode<infer I, infer T> ? Readonly<Record<I, T>> : N extends DictNode<infer K, infer T> ? Readonly<Partial<Record<K, T>>> : N extends ListNode<infer I> ? readonly I[] : N extends TreeNode<infer T> ? DocumentTreeValue<T> : never;
+} : N extends MapNode<infer V> ? Readonly<Record<string, EntityValue<V>>> : N extends DictNode<infer K, infer T> ? Readonly<Partial<Record<K, T>>> : N extends ListNode<infer I> ? readonly I[] : N extends TreeNode<infer T> ? DocumentTreeValue<T> : never;
 type OptionalKeys<S extends ObjectShape> = { [K in keyof S]: S[K] extends {
   readonly optional: true;
 } ? K : never }[keyof S];
@@ -98,43 +91,35 @@ type ImpactTarget<T = unknown> = {
   readonly at: DocumentAddress;
   readonly id?: string;
 } | CollectionSelector<string>;
+declare const pathValue: unique symbol;
+declare const collectionNode: unique symbol;
 type PathMarker<TValue> = {
-  readonly __value?: TValue;
+  readonly [pathValue]: TValue;
 };
-type SchemaPathFor<S extends ObjectShape = ObjectShape, TValue = unknown> = { readonly [K in keyof S]: PathValue<S[K]> } & {
-  readonly item: (id: string) => SchemaPathFor<{}, unknown>;
-} & PathMarker<TValue>;
+type SchemaPathFor<S extends ObjectShape = ObjectShape, TValue = unknown> = { readonly [K in keyof S]: PathValue<S[K]> } & PathMarker<TValue>;
 type DocumentSchema<TShape extends ObjectShape = {}> = {
   readonly kind: 'schema';
   readonly shape: TShape;
-  collection<TPath extends PathMarker<unknown>>(pick: (path: SchemaPath<TShape>) => TPath): CollectionSelector<CollectionId<TPath>, CollectionNode<TPath>>;
+  collection<TPath extends CollectionPath>(pick: (path: SchemaPath<TShape>) => TPath): CollectionSelector<CollectionId<TPath>, CollectionNode<TPath>>;
   value<TPath extends PathMarker<unknown>>(pick: (path: SchemaPath<TShape>) => TPath): ValueSelector<PathValueResult<TPath>>;
 };
 type SchemaPath<S extends ObjectShape = {}> = SchemaPathFor<S, DocumentValueOfShape<S>>;
 type VariantKeys<V extends VariantShape> = { [K in keyof V & string]: keyof (V[K] extends ObjectNode<infer S> ? S : {}) }[keyof V & string] & string;
 type VariantFieldPath<V extends VariantShape, K extends string> = { [P in keyof V & string]: V[P] extends ObjectNode<infer S> ? K extends keyof S ? PathValue<S[K]> : never : never }[keyof V & string];
-type VariantPath<V extends VariantShape> = { readonly [K in VariantKeys<V>]: VariantFieldPath<V, K> } & {
-  readonly item: (id: string) => SchemaPathFor<{}, unknown>;
-} & PathMarker<EntityValue<VariantNode<string, V>>>;
+type VariantPath<T extends string, V extends VariantShape> = { readonly [K in VariantKeys<V>]: VariantFieldPath<V, K> } & { readonly [K in T]: PathMarker<keyof V & string> } & PathMarker<EntityValue<VariantNode<T, V>>>;
 type PathNodeValue<N extends DocumentNode> = N extends {
   readonly optional: true;
 } ? DocumentValueOfNode<N> | undefined : DocumentValueOfNode<N>;
-type EntityPath<N extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = N extends ObjectNode<infer S> ? SchemaPathFor<S, PathNodeValue<N>> : N extends VariantNode<string, infer V> ? VariantPath<V> : never;
-type CollectionPath<N extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = Omit<EntityPath<N>, 'item'> & {
+type EntityPath<N extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = N extends ObjectNode<infer S> ? SchemaPathFor<S, PathNodeValue<N>> : N extends VariantNode<infer T, infer V> ? VariantPath<T, V> : never;
+type CollectionPath<N extends EntitySchemaNode = EntitySchemaNode, TValue = unknown> = PathMarker<TValue> & {
   readonly item: (id: string) => EntityPath<N>;
-  readonly __collection?: {
-    readonly id: string;
-    readonly node: N;
-  };
+  readonly [collectionNode]: N;
 };
-type PathValue<N extends DocumentNode> = N extends ObjectNode<infer S> ? SchemaPathFor<S, PathNodeValue<N>> : N extends VariantNode<infer _TTag, infer V> ? VariantPath<V> : N extends TableNode<infer V> | MapNode<infer V> ? CollectionPath<V> : N extends SingleNode<infer V> ? EntityPath<V> : SchemaPathFor<{}, PathNodeValue<N>>;
+type PathValue<N extends DocumentNode> = N extends ObjectNode<infer S> ? SchemaPathFor<S, PathNodeValue<N>> : N extends VariantNode<infer TTag, infer V> ? VariantPath<TTag, V> : N extends TableNode<infer V> | MapNode<infer V> ? CollectionPath<V, PathNodeValue<N>> : PathMarker<PathNodeValue<N>>;
 type CollectionInfo<T> = T extends {
-  readonly __collection?: {
-    readonly id: infer TId;
-    readonly node: infer TNode extends EntitySchemaNode;
-  };
+  readonly [collectionNode]: infer TNode extends EntitySchemaNode;
 } ? {
-  readonly id: TId;
+  readonly id: string;
   readonly node: TNode;
 } : never;
 type CollectionId<T> = CollectionInfo<T> extends {
@@ -145,13 +130,12 @@ type CollectionNode<T> = CollectionInfo<T> extends {
 } ? TNode : EntitySchemaNode;
 type PathValueResult<T> = T extends PathMarker<infer TValue> ? TValue : unknown;
 declare const field: <T>() => FieldNode<T>;
-declare const optional: <T extends DocumentNode>(value: T) => OptionalNode<T>;
+type OptionalLeaf = FieldNode<unknown, boolean> | VariantNode<string, VariantShape> | DictNode<string, unknown> | ListNode<unknown> | TreeNode<unknown>;
+declare const optional: <T extends OptionalLeaf>(value: T) => OptionalNode<T>;
 declare const object: <S extends ObjectShape>(shape: S) => ObjectNode<S>;
 declare const variant: <T extends string, V extends VariantShape>(tag: T, variants: V) => VariantNode<T, V>;
-declare const single: <V extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>>(value: V) => SingleNode<V>;
 declare const table: <V extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>>(value: V) => TableNode<V>;
 declare const map: <V extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>>(value: V) => MapNode<V>;
-declare const record: <TId extends string = string, TValue = unknown>() => RecordNode<TId, TValue>;
 declare const dict: <TKey extends string = string, TValue = unknown>() => DictNode<TKey, TValue>;
 declare const list: <TItem>(config: DocumentListConfig<TItem>) => ListNode<TItem>;
 declare const tree: <TValue = unknown>() => TreeNode<TValue>;
@@ -168,34 +152,34 @@ type DocumentAnchor = {
 type OperationBase = {
   readonly at: DocumentAddress;
 };
-type FieldSetOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type FieldSetOperation = OperationBase & {
   readonly type: 'field.set';
   readonly value: unknown;
 };
-type FieldClearOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type FieldClearOperation = OperationBase & {
   readonly type: 'field.clear';
 };
-type ValueClearOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type ValueClearOperation = OperationBase & {
   readonly type: 'value.clear';
 };
-type VariantReplaceOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type VariantReplaceOperation = OperationBase & {
   readonly type: 'variant.replace';
   readonly value: unknown;
 };
-type DictSetOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type DictSetOperation = OperationBase & {
   readonly type: 'dict.set';
   readonly key: string;
   readonly value: unknown;
 };
-type DictDeleteOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type DictDeleteOperation = OperationBase & {
   readonly type: 'dict.delete';
   readonly key: string;
 };
-type DictReplaceOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type DictReplaceOperation = OperationBase & {
   readonly type: 'dict.replace';
   readonly value: Readonly<Record<string, unknown>>;
 };
-type EntityCreateOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type EntityCreateOperation = OperationBase & {
   readonly type: 'entity.create';
   readonly entries: readonly EntityEntry[];
   readonly anchor?: DocumentAnchor; /** Generated inverse metadata with strictly increasing final indices. Normal creates omit it. */
@@ -205,74 +189,81 @@ type EntityEntry = {
   readonly id: string;
   readonly value: unknown;
 };
-type EntityRemoveOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type EntityRemoveOperation = OperationBase & {
   readonly type: 'entity.remove';
   readonly ids: readonly string[];
 };
-type EntityMoveOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type EntityMoveOperation = OperationBase & {
   readonly type: 'entity.move';
   readonly id: string;
   readonly anchor?: DocumentAnchor;
 };
-type ListInsertOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type ListInsertOperation = OperationBase & {
   readonly type: 'list.insert';
   readonly key: string;
   readonly value: unknown;
   readonly anchor?: DocumentAnchor;
 };
-type ListMoveOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type ListMoveOperation = OperationBase & {
   readonly type: 'list.move';
   readonly key: string;
   readonly anchor?: DocumentAnchor;
 };
-type ListRemoveOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type ListRemoveOperation = OperationBase & {
   readonly type: 'list.remove';
   readonly key: string;
 };
-type ListReplaceOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type ListReplaceOperation = OperationBase & {
   readonly type: 'list.replace';
   readonly value: readonly unknown[];
   readonly keys: readonly string[];
 };
-type TreeInsertOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type TreeInsertOperation = OperationBase & {
   readonly type: 'tree.insert';
   readonly treeNodeId: string;
   readonly parentId?: string;
   readonly index?: number;
   readonly value?: unknown;
 };
-type TreeMoveOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type TreeMoveOperation = OperationBase & {
   readonly type: 'tree.move';
   readonly treeNodeId: string;
   readonly parentId?: string;
   readonly index?: number;
 };
-type TreeRemoveOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type TreeRemoveOperation = OperationBase & {
   readonly type: 'tree.remove';
   readonly treeNodeId: string;
 };
-type TreeSetOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type TreeSetOperation = OperationBase & {
   readonly type: 'tree.set';
   readonly treeNodeId: string;
   readonly value: unknown;
 };
-type TreeReplaceOperation<TSchema extends DocumentSchema = DocumentSchema> = OperationBase & {
+type TreeReplaceOperation = OperationBase & {
   readonly type: 'tree.replace';
   readonly value: unknown;
 };
-type DocumentOperationUnion<TSchema extends DocumentSchema = DocumentSchema> = FieldSetOperation<TSchema> | FieldClearOperation<TSchema> | ValueClearOperation<TSchema> | VariantReplaceOperation<TSchema> | DictSetOperation<TSchema> | DictDeleteOperation<TSchema> | DictReplaceOperation<TSchema> | EntityCreateOperation<TSchema> | EntityRemoveOperation<TSchema> | EntityMoveOperation<TSchema> | ListInsertOperation<TSchema> | ListMoveOperation<TSchema> | ListRemoveOperation<TSchema> | ListReplaceOperation<TSchema> | TreeInsertOperation<TSchema> | TreeMoveOperation<TSchema> | TreeRemoveOperation<TSchema> | TreeSetOperation<TSchema> | TreeReplaceOperation<TSchema>;
-type DocumentOperation<TSchema extends DocumentSchema = DocumentSchema> = DocumentOperationUnion<TSchema>;
+type DocumentOperation = FieldSetOperation | FieldClearOperation | ValueClearOperation | VariantReplaceOperation | DictSetOperation | DictDeleteOperation | DictReplaceOperation | EntityCreateOperation | EntityRemoveOperation | EntityMoveOperation | ListInsertOperation | ListMoveOperation | ListRemoveOperation | ListReplaceOperation | TreeInsertOperation | TreeMoveOperation | TreeRemoveOperation | TreeSetOperation | TreeReplaceOperation;
 //#endregion
 //#region core/src/access/reader.d.ts
 type FieldReader<T> = {
   readonly get: () => T;
 };
+type DictionaryReader<K extends string, V> = {
+  get(key: K): V | undefined;
+  has(key: K): boolean;
+  keys(): readonly K[];
+  values(): Readonly<Partial<Record<K, V>>>;
+};
 type CollectionReader<TId, TNode extends EntitySchemaNode> = {
   readonly ids: () => readonly TId[];
   readonly has: (id: TId) => boolean;
   readonly get: (id: TId) => ReaderOfNode<TNode> | undefined;
 };
 type ListReader<T> = {
+  readonly get: (key: string) => T | undefined;
+  readonly has: (key: string) => boolean;
   readonly values: () => readonly T[];
   readonly length: () => number;
   readonly at: (index: number) => T | undefined;
@@ -286,7 +277,9 @@ type TreeReader<T> = {
 };
 type ReaderOfNode<TNode extends DocumentNode> = TNode extends {
   kind: 'field';
-} ? FieldReader<DocumentValueOfNode<TNode>> : TNode extends ObjectNode<infer TShape> ? { readonly [K in keyof TShape]: ReaderOfNode<TShape[K]> } : TNode extends VariantNode<string, infer TVariants> ? { readonly [K in keyof TVariants]: ReaderOfNode<TVariants[K]> } : TNode extends SingleNode<infer TValue> ? ReaderOfNode<TValue> : TNode extends TableNode<infer TValue> ? CollectionReader<string, TValue> : TNode extends MapNode<infer TValue> ? CollectionReader<string, TValue> : TNode extends DictNode<infer TKey, infer TValue> ? FieldReader<Readonly<Partial<Record<TKey, TValue>>>> : TNode extends ListNode<infer TItem> ? ListReader<TItem> : TNode extends TreeNode<infer TValue> ? TreeReader<TValue> : FieldReader<DocumentValueOfNode<TNode>>;
+} ? FieldReader<DocumentValueOfNode<TNode>> : TNode extends ObjectNode<infer TShape> ? { readonly [K in keyof TShape]: ReaderOfNode<TShape[K]> } : TNode extends VariantNode<string, infer _TVariants> ? FieldReader<DocumentValueOfNode<TNode> | (TNode extends {
+  readonly optional: true;
+} ? undefined : never)> : TNode extends TableNode<infer TValue> ? CollectionReader<string, TValue> : TNode extends MapNode<infer TValue> ? CollectionReader<string, TValue> : TNode extends DictNode<infer TKey, infer TValue> ? DictionaryReader<TKey, TValue> : TNode extends ListNode<infer TItem> ? ListReader<TItem> : TNode extends TreeNode<infer TValue> ? TreeReader<TValue> : FieldReader<DocumentValueOfNode<TNode>>;
 type DocumentReader<TSchema extends DocumentSchema> = ReaderOfNode<ObjectNode<TSchema['shape']>>;
 //#endregion
 //#region core/src/access/writer.d.ts
@@ -330,8 +323,14 @@ type ListWriter<T> = {
   readonly replace: (value: readonly T[]) => void;
 };
 type TreeWriter<T> = {
-  readonly insert: (id: string, value: T, parentId?: string, index?: number) => void;
-  readonly move: (id: string, parentId?: string, index?: number) => void;
+  readonly insert: (id: string, value: T, position?: {
+    readonly parentId?: string;
+    readonly index?: number;
+  }) => void;
+  readonly move: (id: string, position?: {
+    readonly parentId?: string;
+    readonly index?: number;
+  }) => void;
   readonly remove: (id: string) => void;
   readonly set: (id: string, value: T) => void;
   readonly replace: (value: DocumentTreeValue<T>) => void;
@@ -347,7 +346,7 @@ type WriterOfNode<TNode extends DocumentNode> = TNode extends {
   readonly optional: true;
 } ? FieldWriter<DocumentValueOfNode<TNode>, true> : FieldWriter<DocumentValueOfNode<TNode>> : TNode extends ObjectNode<infer TShape> ? { readonly [K in keyof TShape]: WriterOfNode<TShape[K]> } : TNode extends VariantNode<string, infer _TVariants> ? OptionalClear<TNode, {
   readonly replace: (value: DocumentValueOfNode<TNode>) => void;
-}> : TNode extends SingleNode<infer TValue> ? WriterOfNode<TValue> : TNode extends TableNode<infer TValue> ? CollectionWriter<string, TValue> : TNode extends MapNode<infer TValue> ? MapWriter<string, TValue> : TNode extends DictNode<infer TKey, infer TValue> ? OptionalClear<TNode, DictionaryWriter<TKey, TValue>> : TNode extends ListNode<infer TItem> ? OptionalClear<TNode, ListWriter<TItem>> : TNode extends TreeNode<infer TValue> ? OptionalClear<TNode, TreeWriter<TValue>> : FieldWriter<DocumentValueOfNode<TNode>>;
+}> : TNode extends TableNode<infer TValue> ? CollectionWriter<string, TValue> : TNode extends MapNode<infer TValue> ? MapWriter<string, TValue> : TNode extends DictNode<infer TKey, infer TValue> ? OptionalClear<TNode, DictionaryWriter<TKey, TValue>> : TNode extends ListNode<infer TItem> ? OptionalClear<TNode, ListWriter<TItem>> : TNode extends TreeNode<infer TValue> ? OptionalClear<TNode, TreeWriter<TValue>> : FieldWriter<DocumentValueOfNode<TNode>>;
 type DocumentWriter<TSchema extends DocumentSchema> = WriterOfNode<ObjectNode<TSchema['shape']>>;
 //#endregion
 //#region core/src/mutation/issue.d.ts
@@ -357,7 +356,7 @@ type MutationIssue = {
   readonly code: MutationIssueCode;
   readonly address: DocumentAddress;
   readonly message: string;
-  readonly operation?: DocumentOperationUnion['type'];
+  readonly operation?: DocumentOperation['type'];
 };
 //#endregion
 //#region core/src/impact.d.ts
@@ -374,7 +373,7 @@ type DocumentImpact<TSchema extends DocumentSchema> = {
   readonly kind: 'incremental' | 'reset';
   readonly affects: (target: ImpactTarget<unknown>) => boolean;
   readonly collection: <TId extends string>(selector: CollectionSelector<TId>) => CollectionImpact<TId>;
-  readonly operations: readonly DocumentOperationUnion<TSchema>[];
+  readonly operations: readonly DocumentOperation[];
 };
 //#endregion
 //#region core/src/address.d.ts
@@ -423,12 +422,20 @@ type CommandFootprintTarget = {
   readonly id: string;
 };
 type CommandFootprint = readonly CommandFootprintTarget[];
-declare const commandFootprint: (operations: readonly DocumentOperationUnion[]) => CommandFootprint;
+declare const commandFootprint: (operations: readonly DocumentOperation[]) => CommandFootprint;
 declare const footprintsOverlap: (left: CommandFootprint, right: CommandFootprint) => boolean;
 declare const decodeCommandFootprint: (value: unknown) => CommandFootprint | undefined;
 //#endregion
+//#region core/src/projection/readable.d.ts
+type Readable<TValue> = {
+  current(): TValue;
+  revision(): number;
+  subscribe(listener: () => void): Unsubscribe;
+};
+//#endregion
 //#region core/src/runtime/contract.d.ts
 type Unsubscribe = () => void;
+type Synchronous<T> = T extends PromiseLike<unknown> ? never : T;
 type CommitSource = 'local' | 'system' | 'history' | 'remote';
 declare class DocumentReentrancyError extends Error {
   constructor();
@@ -440,16 +447,18 @@ type DocumentCommit<TSchema extends DocumentSchema> = {
   readonly revision: number;
   readonly kind: 'operations' | 'replace';
   readonly source: CommitSource;
-  readonly operations: readonly DocumentOperationUnion<TSchema>[];
-  readonly inverse: readonly DocumentOperationUnion<TSchema>[];
+  readonly operations: readonly DocumentOperation[];
+  readonly inverse: readonly DocumentOperation[];
   readonly impact: DocumentImpact<TSchema>;
 };
-type DocumentDiagnostic = {
-  readonly source: 'application';
+type DiagnosticInput = {
   readonly code: string;
   readonly message: string;
   readonly address?: DocumentAddress;
 };
+type DocumentDiagnostic = DiagnosticInput & {
+  readonly source: 'application';
+};
 type DocumentProblem = DocumentDiagnostic | MutationIssue;
 type ObserverError = {
   readonly phase: 'processor' | 'flush' | 'listener';
@@ -474,8 +483,8 @@ type TransactionResult<TValue, TCommit> = {
 type PreparedUpdateResult<TValue, TSchema extends DocumentSchema> = {
   readonly status: 'prepared';
   readonly value: TValue;
-  readonly operations: readonly DocumentOperationUnion<TSchema>[];
-  readonly inverse: readonly DocumentOperationUnion<TSchema>[];
+  readonly operations: readonly DocumentOperation[];
+  readonly inverse: readonly DocumentOperation[];
   readonly impact: DocumentImpact<TSchema>;
   readonly footprint: CommandFootprint;
   readonly reports: readonly DocumentDiagnostic[];
@@ -503,18 +512,20 @@ type HistoryState = {
   readonly undoDepth: number;
   readonly redoDepth: number;
 };
-type LocalHistory<TCommit> = {
-  current(): HistoryState;
-  subscribe(listener: () => void): Unsubscribe;
+type LocalHistory<TCommit> = Readable<HistoryState> & {
   undo(): OperationResult<TCommit>;
   redo(): OperationResult<TCommit>;
   clear(): void;
+  group(): {
+    end(): void;
+    cancel(): OperationResult<TCommit>;
+  };
 };
 type DocumentTransaction<TSchema extends DocumentSchema> = {
   readonly read: DocumentReader<TSchema>;
   readonly write: DocumentWriter<TSchema>;
-  readonly reject: (issue: DocumentDiagnostic | readonly DocumentDiagnostic[]) => never;
-  readonly report: (issue: DocumentDiagnostic) => void;
+  readonly reject: (issue: DiagnosticInput | readonly DiagnosticInput[]) => never;
+  readonly report: (issue: DiagnosticInput) => void;
 };
 type CommitListener<TSchema extends DocumentSchema> = (commit: DocumentCommit<TSchema>) => void;
 type DocumentReadable<TSchema extends DocumentSchema> = {
@@ -531,11 +542,11 @@ type DocumentReadable<TSchema extends DocumentSchema> = {
 };
 type DocumentRuntime<TSchema extends DocumentSchema> = DocumentReadable<TSchema> & {
   /** Schema configuration captured when this runtime was created. */readonly schema: TSchema;
-  update<TResult>(run: (transaction: DocumentTransaction<TSchema>) => TResult, options?: {
+  update<TResult>(run: (transaction: DocumentTransaction<TSchema>) => Synchronous<TResult>, options?: {
     readonly source?: Extract<CommitSource, 'local' | 'system'>;
     readonly history?: boolean;
   }): TransactionResult<TResult, DocumentCommit<TSchema>>;
-  prepare<TResult>(run: (transaction: DocumentTransaction<TSchema>) => TResult): PreparedUpdateResult<TResult, TSchema>;
+  prepare<TResult>(run: (transaction: DocumentTransaction<TSchema>) => Synchronous<TResult>): PreparedUpdateResult<TResult, TSchema>;
   apply(operations: unknown, options?: {
     readonly source?: Exclude<CommitSource, 'history'>;
     readonly history?: boolean;
@@ -548,5 +559,5 @@ type DocumentRuntime<TSchema extends DocumentSchema> = DocumentReadable<TSchema>
   dispose(): void;
 };
 //#endregion
-export { EntityEntry as $, tree as $t, MutationIssue as A, MapNode as At, CollectionReader as B, ValueSelector as Bt, contains as C, DocumentTreeValue as Ct, resolveAddress as D, FieldNode as Dt, read as E, EntitySchemaNode as Et, FieldWriter as F, RecordNode as Ft, TreeReader as G, list as Gt, FieldReader as H, VariantShape as Ht, ListWriter as I, SchemaPath as It, DictSetOperation as J, optional as Jt, DictDeleteOperation as K, map as Kt, MapWriter as L, SingleNode as Lt, CollectionWriter as M, ObjectShape as Mt, DictionaryWriter as N, OptionalNode as Nt, CollectionImpact as O, ImpactTarget as Ot, DocumentWriter as P, ReadonlyDocument as Pt, EntityCreateOperation as Q, table as Qt, TreeWriter as R, TableNode as Rt, AddressRef as S, DocumentTreeNode as St, overlaps as T, DocumentValueOfShape as Tt, ListReader as U, dict as Ut, DocumentReader as V, VariantNode as Vt, ReaderOfNode as W, field as Wt, DocumentOperation as X, schema as Xt, DocumentAnchor as Y, record as Yt, DocumentOperationUnion as Z, single as Zt, CommandFootprint as _, DictNode as _t, DocumentProblem as a, ListMoveOperation as at, decodeCommandFootprint as b, DocumentNode as bt, DocumentRuntime as c, TreeInsertOperation as ct, LocalHistory as d, TreeReplaceOperation as dt, variant as en, EntityMoveOperation as et, ObserverError as f, TreeSetOperation as ft, Unsubscribe as g, CollectionSelector as gt, TransactionResult as h, CollectionNode as ht, DocumentDisposedError as i, ListInsertOperation as it, MutationIssueCode as j, ObjectNode as jt, DocumentImpact as k, ListNode as kt, DocumentTransaction as l, TreeMoveOperation as lt, PreparedUpdateResult as m, VariantReplaceOperation as mt, DocumentCommit as n, FieldClearOperation as nt, DocumentReadable as o, ListRemoveOperation as ot, OperationResult as p, ValueClearOperation as pt, DictReplaceOperation as q, object as qt, DocumentDiagnostic as r, FieldSetOperation as rt, DocumentReentrancyError as s, ListReplaceOperation as st, CommitSource as t, EntityRemoveOperation as tt, HistoryState as u, TreeRemoveOperation as ut, CommandFootprintTarget as v, DocumentAddress as vt, debugKey as w, DocumentValueOfNode as wt, footprintsOverlap as x, DocumentSchema as xt, commandFootprint as y, DocumentListConfig as yt, WriterOfNode as z, TreeNode as zt };
-//# sourceMappingURL=contract-4E3moCbY.d.ts.map
+export { DocumentOperation as $, variant as $t, CollectionImpact as A, FieldNode as At, TreeWriter as B, TreeNode as Bt, footprintsOverlap as C, DocumentNode as Ct, overlaps as D, DocumentValueOfNode as Dt, debugKey as E, DocumentTreeValue as Et, DictionaryWriter as F, ObjectShape as Ft, FieldReader as G, field as Gt, CollectionReader as H, VariantNode as Ht, DocumentWriter as I, OptionalNode as It, TreeReader as J, object as Jt, ListReader as K, list as Kt, FieldWriter as L, ReadonlyDocument as Lt, MutationIssue as M, ListNode as Mt, MutationIssueCode as N, MapNode as Nt, read as O, DocumentValueOfShape as Ot, CollectionWriter as P, ObjectNode as Pt, DocumentAnchor as Q, tree as Qt, ListWriter as R, SchemaPath as Rt, decodeCommandFootprint as S, DocumentListConfig as St, contains as T, DocumentTreeNode as Tt, DictionaryReader as U, VariantShape as Ut, WriterOfNode as V, ValueSelector as Vt, DocumentReader as W, dict as Wt, DictReplaceOperation as X, schema as Xt, DictDeleteOperation as Y, optional as Yt, DictSetOperation as Z, table as Zt, Unsubscribe as _, CollectionNode as _t, DocumentProblem as a, FieldSetOperation as at, CommandFootprintTarget as b, DictNode as bt, DocumentRuntime as c, ListRemoveOperation as ct, LocalHistory as d, TreeMoveOperation as dt, EntityCreateOperation as et, ObserverError as f, TreeRemoveOperation as ft, TransactionResult as g, VariantReplaceOperation as gt, Synchronous as h, ValueClearOperation as ht, DocumentDisposedError as i, FieldClearOperation as it, DocumentImpact as j, ImpactTarget as jt, resolveAddress as k, EntitySchemaNode as kt, DocumentTransaction as l, ListReplaceOperation as lt, PreparedUpdateResult as m, TreeSetOperation as mt, DocumentCommit as n, EntityMoveOperation as nt, DocumentReadable as o, ListInsertOperation as ot, OperationResult as p, TreeReplaceOperation as pt, ReaderOfNode as q, map as qt, DocumentDiagnostic as r, EntityRemoveOperation as rt, DocumentReentrancyError as s, ListMoveOperation as st, CommitSource as t, EntityEntry as tt, HistoryState as u, TreeInsertOperation as ut, Readable as v, CollectionPath as vt, AddressRef as w, DocumentSchema as wt, commandFootprint as x, DocumentAddress as xt, CommandFootprint as y, CollectionSelector as yt, MapWriter as z, TableNode as zt };
+//# sourceMappingURL=contract-DNZ4D53r.d.ts.map