doxum 0.1.6 → 0.1.8

package/README.md

@@ -61,7 +61,7 @@ Define the document shape once. Doxum infers the immutable document value and
 the reader and writer APIs from that schema.
 
 ```ts
-import { createDocument, field, object, schema, table } from 'doxum';
+import { createDocument, field, object, schema, table, type Infer } from 'doxum';
 
 const task = object({
   title: field<string>(),
@@ -73,6 +73,9 @@ const taskSchema = schema({
   tasks: table(task),
 });
 
+type Task = Infer<typeof task>;
+type TaskDocument = Infer<typeof taskSchema>;
+
 const runtime = createDocument({
   schema: taskSchema,
   initial: {
@@ -100,8 +103,33 @@ 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.
+
+## Infer Value Types
+
+Use `Infer<typeof node>` or `Infer<typeof documentSchema>` for value types.
+Schema-generated objects are flattened, with readonly properties and optional
+presence preserved. Variants produce a discriminated union of flat branches:
+
+```ts
+import { field, object, variant, type Infer } from 'doxum';
+
+const outcome = variant('kind', {
+  victory: object({ reason: field<'sealed' | 'destroyed'>() }),
+  defeat: object({ reason: field<'deadline' | 'collapse'>() }),
+});
+
+type Outcome = Infer<typeof outcome>;
+// { readonly kind: 'victory'; readonly reason: 'sealed' | 'destroyed' }
+// | { readonly kind: 'defeat'; readonly reason: 'deadline' | 'collapse' }
+```
+
+`Infer` includes `undefined` for an optional node; in a containing object its
+property is optional. User-supplied types in `field<T>`, dict, list and tree
+values retain their original type structure. Flattening does not recursively
+rewrite those types or apply deep readonly to them. TypeScript controls the
+exact alias presentation in editor hovers.
 
 ## Read And Subscribe
 
@@ -141,6 +169,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 +212,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 +232,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 +246,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
@@ -250,23 +289,28 @@ const taskTitles = projection.map(
   document.collection(path => path.tasks),
   (_id, task) => task.title.get()
 );
-const taskCount = projection.value({
-  sources: { tasks: taskTitles },
-  build: ({ tasks }) => ({
-    value: tasks.ids().length,
-    update: ({ tasks }) => ({ kind: 'changed', value: tasks.ids().length }),
-  }),
-});
+const taskCount = projection.value({ tasks: taskTitles }, ({ tasks }) => tasks.ids().length);
+const labels = projection.map(taskTitles, (id, title) => `${id}: ${title}`);
 ```
 
-`projection.collection(spec)` handles custom incremental algorithms. Its scoped
+`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. Doxum stages writes,
+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.
@@ -286,6 +330,15 @@ 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

package/dist/{contract-I99DUMbN.d.ts → contract-CIcftgR3.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,18 +57,21 @@ 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 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 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 SchemaObject<T> = { [K in keyof T]: T[K] } & {};
+/** Infer a document or node value, including optional node presence. */
+type Infer<T extends DocumentNode | DocumentSchema> = T extends DocumentSchema<infer S> ? ShapeValue<S> : T extends {
+  readonly optional: true;
+} ? NodeValue<T> | undefined : NodeValue<T>;
+type NodeValue<N> = N extends FieldNode<infer T, infer O> ? O extends true ? T | undefined : T : N extends ObjectNode<infer S> ? ShapeValue<S> : N extends VariantNode<infer T, infer V> ? { [K in keyof V & string]: SchemaObject<{ readonly [P in T]: K } & NodeValue<V[K]>> }[keyof V & string] : 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;
+  readonly byId: Readonly<Record<string, NodeValue<V>>>;
+} : N extends MapNode<infer V> ? Readonly<Record<string, NodeValue<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];
 type RequiredKeys<S extends ObjectShape> = Exclude<keyof S, OptionalKeys<S>>;
-type DocumentValueOfShape<S extends ObjectShape> = { readonly [K in RequiredKeys<S>]: DocumentValueOfNode<S[K]> } & { readonly [K in OptionalKeys<S>]?: DocumentValueOfNode<S[K]> };
-type ReadonlyDocument<S extends DocumentSchema> = DocumentValueOfShape<S['shape']>;
+type ShapeValue<S extends ObjectShape> = SchemaObject<{ readonly [K in RequiredKeys<S>]: NodeValue<S[K]> } & { readonly [K in OptionalKeys<S>]?: NodeValue<S[K]> }>;
 type EntitySchemaNode = ObjectNode<ObjectShape> | VariantNode<string, VariantShape>;
 type CollectionSelector<TId extends string = string, TNode extends EntitySchemaNode = EntitySchemaNode> = {
   readonly kind: 'collection';
@@ -98,43 +94,32 @@ 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 SchemaPath<S extends ObjectShape = {}> = SchemaPathFor<S, ShapeValue<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 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 VariantPath<T extends string, V extends VariantShape, TValue> = { readonly [K in VariantKeys<V>]: VariantFieldPath<V, K> } & { readonly [K in T]: PathMarker<keyof V & string> } & PathMarker<TValue>;
+type EntityPath<N extends ObjectNode<ObjectShape> | VariantNode<string, VariantShape>> = N extends ObjectNode<infer S> ? SchemaPathFor<S, Infer<N>> : N extends VariantNode<infer T, infer V> ? VariantPath<T, V, Infer<N>> : 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, Infer<N>> : N extends VariantNode<infer TTag, infer V> ? VariantPath<TTag, V, Infer<N>> : N extends TableNode<infer V> | MapNode<infer V> ? CollectionPath<V, Infer<N>> : PathMarker<Infer<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,7 @@ 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<Infer<TNode>> : TNode extends ObjectNode<infer TShape> ? { readonly [K in keyof TShape]: ReaderOfNode<TShape[K]> } : TNode extends VariantNode<string, infer _TVariants> ? FieldReader<Infer<TNode>> : 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<Infer<TNode>>;
 type DocumentReader<TSchema extends DocumentSchema> = ReaderOfNode<ObjectNode<TSchema['shape']>>;
 //#endregion
 //#region core/src/access/writer.d.ts
@@ -303,10 +294,10 @@ type DictionaryWriter<TKey extends string, TValue> = {
 type CollectionWriter<TId, TNode extends EntitySchemaNode> = {
   readonly create: (entry: {
     readonly id: TId;
-    readonly value: DocumentValueOfNode<TNode>;
+    readonly value: Exclude<Infer<TNode>, undefined>;
   } | readonly {
     readonly id: TId;
-    readonly value: DocumentValueOfNode<TNode>;
+    readonly value: Exclude<Infer<TNode>, undefined>;
   }[], anchor?: DocumentAnchor) => void;
   readonly item: (id: TId) => WriterOfNode<TNode>;
   readonly remove: (id: TId | readonly TId[]) => void;
@@ -315,10 +306,10 @@ type CollectionWriter<TId, TNode extends EntitySchemaNode> = {
 type MapWriter<TId, TNode extends EntitySchemaNode> = {
   readonly create: (entry: {
     readonly id: TId;
-    readonly value: DocumentValueOfNode<TNode>;
+    readonly value: Exclude<Infer<TNode>, undefined>;
   } | readonly {
     readonly id: TId;
-    readonly value: DocumentValueOfNode<TNode>;
+    readonly value: Exclude<Infer<TNode>, undefined>;
   }[]) => void;
   readonly item: (id: TId) => WriterOfNode<TNode>;
   readonly remove: (id: TId | readonly TId[]) => void;
@@ -330,8 +321,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;
@@ -345,9 +342,9 @@ type WriterOfNode<TNode extends DocumentNode> = TNode extends {
   kind: 'field';
 } ? 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>>;
+} ? FieldWriter<Infer<TNode>, true> : FieldWriter<Infer<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: Exclude<Infer<TNode>, undefined>) => void;
+}> : 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<Infer<TNode>>;
 type DocumentWriter<TSchema extends DocumentSchema> = WriterOfNode<ObjectNode<TSchema['shape']>>;
 //#endregion
 //#region core/src/mutation/issue.d.ts
@@ -357,7 +354,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 +371,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 +420,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 +445,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 +481,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 +510,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,22 +540,22 @@ 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;
   }): OperationResult<DocumentCommit<TSchema>>;
-  replace(document: ReadonlyDocument<TSchema>, options?: {
+  replace(document: Infer<TSchema>, options?: {
     readonly source?: Extract<CommitSource, 'system' | 'remote'>;
   }): OperationResult<DocumentCommit<TSchema>>;
-  snapshot(): ReadonlyDocument<TSchema>;
+  snapshot(): Infer<TSchema>;
   readonly history: LocalHistory<DocumentCommit<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-I99DUMbN.d.ts.map
+export { DocumentOperation as $, CollectionImpact as A, Infer as At, TreeWriter as B, VariantNode as Bt, footprintsOverlap as C, DocumentNode as Ct, overlaps as D, EntitySchemaNode as Dt, debugKey as E, DocumentTreeValue as Et, DictionaryWriter as F, OptionalNode as Ft, FieldReader as G, map as Gt, CollectionReader as H, dict as Ht, DocumentWriter as I, SchemaPath as It, TreeReader as J, schema as Jt, ListReader as K, object as Kt, FieldWriter as L, TableNode as Lt, MutationIssue as M, MapNode as Mt, MutationIssueCode as N, ObjectNode as Nt, read as O, FieldNode as Ot, CollectionWriter as P, ObjectShape as Pt, DocumentAnchor as Q, ListWriter as R, TreeNode as Rt, decodeCommandFootprint as S, DocumentListConfig as St, contains as T, DocumentTreeNode as Tt, DictionaryReader as U, field as Ut, WriterOfNode as V, VariantShape as Vt, DocumentReader as W, list as Wt, DictReplaceOperation as X, tree as Xt, DictDeleteOperation as Y, table as Yt, DictSetOperation as Z, variant 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, ListNode as jt, resolveAddress as k, ImpactTarget 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, optional 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, ValueSelector as zt };
+//# sourceMappingURL=contract-CIcftgR3.d.ts.map