@mmstack/primitives 21.7.0 → 21.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "21.7.0",
+  "version": "21.8.1",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -2806,6 +2806,11 @@ type Key$2 = string | number;
  * One structural operation. `set` on a key that did not previously exist carries NO `prev`
  * property (an absent key is not the same as a key holding `undefined` — the merge3 lesson),
  * which is what lets {@link invertBatch} invert an add into a delete.
+ *
+ * `clear` is a sync-layer intent, not a value change: it retires a per-path register (the
+ * observed-remove half of a subtree replace) and contributes NOTHING to a value: {@link applyOps}
+ * treats it as a no-op and the structural diff ({@link diffOps}) never emits one. Only the sync
+ * emission layer produces clears; they ride batches so undo/rebase plumbing can pass them through.
  */
 type StoreOp = {
     kind: 'set';
@@ -2816,6 +2821,9 @@ type StoreOp = {
     kind: 'delete';
     path: readonly Key$2[];
     prev: unknown;
+} | {
+    kind: 'clear';
+    path: readonly Key$2[];
 };
 /** One emission: every op derived from one commit window (a tick), in path order. */
 type OpBatch = {
@@ -2888,14 +2896,17 @@ declare function applyOps<T>(root: T, ops: OpBatch | readonly StoreOp[]): T;
  * Pure reference-pruned structural diff of two roots into minimal ops (the emission core of
  * {@link opLog}, exported so code outside a log can produce a batch — e.g. diffing a scratch
  * draft against a replica's current value to route a write to its owner). Trusts the
- * copy-on-write contract: an untouched subtree that kept its reference is skipped.
+ * copy-on-write contract: an untouched subtree that kept its reference is skipped. Emits only
+ * `set` and `delete`; `clear` is an emission-layer intent, never a diff product.
  */
 declare function diffOps(prev: unknown, next: unknown): StoreOp[];
 /**
  * Inverts a batch for undo: reversed order, `set`↔its own inverse (an add — a `set` with no
  * `prev` — inverts to a `delete`; a `delete` inverts to a `set` restoring `prev`). Feed the
  * result to {@link OpLog.apply}. Requires the ops' `prev`s, which in-memory batches always
- * carry — a wire-serialized batch that stripped them is not invertible.
+ * carry (a wire-serialized batch that stripped them is not invertible). A `clear` is skipped:
+ * it never changed a value, so it has no independent inverse (the accompanying subtree `set`'s
+ * `prev` subsumes restoration).
  */
 declare function invertBatch(batch: OpBatch | readonly StoreOp[]): StoreOp[];
 /**
@@ -3303,11 +3314,51 @@ type HlcClock = {
  */
 declare function createHlcClock(now?: () => number): HlcClock;
 
-declare const OP_PROTO_VERSION = 1;
+/**
+ * Wire protocol version. Version 2 ops carry `cites` + `epoch` (the dot-citation register);
+ * envelopes from other versions are dropped loudly: an op without citations cannot be merged
+ * soundly (it would supersede nothing and its siblings would accumulate forever), so versions
+ * are never silently mixed.
+ */
+declare const OP_PROTO_VERSION = 2;
 type Key = string | number;
 /**
- * The wire/journal recor. `writer` is an opaque principal pseudonym —
- * natural identity never enters the envelope; `origin` identifies the emitting log instance.
+ * A dot: the globally-unique identity of one op at one path, the emitting replica (`origin`)
+ * plus its clock stamp. Origins are unique per replica and their clocks are monotone, so a dot
+ * never collides. Citing a dot means "I observed this write and am replacing it".
+ */
+type Dot = {
+    readonly origin: string;
+    readonly hlc: Hlc;
+};
+/**
+ * A frozen observation point: the set of writes a replica had seen at a moment in time, captured
+ * cheaply as a monotone sequence marker. Stamping emission against a frontier makes an op cite the
+ * siblings that were live THEN, not the ones live now, so an edit made against stale knowledge (a
+ * fork committed after the base moved on) stays a concurrent sibling instead of superseding writes
+ * it never observed.
+ */
+type DotFrontier = {
+    readonly seq: number;
+};
+/**
+ * A wire op: a structural {@link StoreOp} plus the causal metadata the register needs.
+ * `cites` lists the sibling dot(s) the writer observed at the op's path when it wrote;
+ * exactly those get superseded; a write nobody cited stays live as a concurrent sibling.
+ * `epoch` is the op's precedence term: stamped at emission as the max of the cited dots'
+ * epochs and the writer's own prior epoch at this path (monotone per writer per path), +1
+ * for an authority-bumped write. `prev` (on the underlying op) stays purely an inversion
+ * hint for undo/rebase and plays no role in convergence.
+ */
+type SyncOp = StoreOp & {
+    readonly cites: readonly Dot[];
+    readonly epoch: number;
+};
+/**
+ * The wire/journal record. `writer` is an opaque principal pseudonym (natural identity never
+ * enters the envelope); `origin` identifies the emitting replica. All ops in one envelope share
+ * the envelope stamp, and an envelope carries at most one op per path, so `(origin, hlc)` is a
+ * unique dot per path register.
  */
 type OpEnvelope = {
     readonly proto: number;
@@ -3316,20 +3367,35 @@ type OpEnvelope = {
     readonly version: number;
     readonly hlc: Hlc;
     readonly policyVersion: number;
-    readonly ops: readonly StoreOp[];
+    readonly ops: readonly SyncOp[];
 };
 declare const CONFLICT_BRAND = "~mmstackConflict";
 /**
- * A preserved (jj-style) conflict: both sides survive as data, sync never blocks, and
- * resolution is just a later write. String-branded so it survives structured clone.
+ * A preserved (jj-style) conflict: every concurrent write survives as data, sync never blocks,
+ * and resolution is just a later write (which cites all surviving dots and collapses the set).
+ * `siblings` holds every live top-precedence value, winner first; a concurrent delete surfaces
+ * as `undefined`. `mine`/`theirs` alias the first two entries, the shape two-sided reconcile
+ * seams (fork rebase) produce and consume. String-branded so it survives structured clone.
  */
 type Conflicted<T = unknown> = {
     readonly [CONFLICT_BRAND]: true;
+    readonly siblings: readonly T[];
     readonly mine: T;
     readonly theirs: T;
     readonly ancestor?: T;
 };
 declare function isConflicted<T = unknown>(value: unknown): value is Conflicted<T>;
+/**
+ * Deterministic, total well-formedness check for a received envelope. Returns a short reason
+ * string when the envelope must be rejected WHOLE, or `null` when it is well-formed. It reads only
+ * the envelope (no clock, no local state), so every replica accepts or rejects a given envelope
+ * identically. This validates SHAPE, not authority: it closes malformed input (control characters
+ * in an id or path segment that could forge a path-key separator, a non-integer version, an unknown
+ * op kind, a negative epoch, forged cites, a root delete, two ops racing on one path). Authority and
+ * access control stay at the relay; direct peer-to-peer rooms are trust-full for authority, so this
+ * shape check is a peer's only line against a malformed neighbor.
+ */
+declare function validateEnvelope(env: OpEnvelope): string | null;
 type MergeContext = {
     readonly path: readonly Key[];
 };
@@ -3352,32 +3418,146 @@ declare const preserve: MergeFn;
  * array. Items are matched by key; per-item fields merge via `merge3` against the ancestor
  * item; items added on either side survive; an item removed on either side and unedited on
  * the other stays removed. Item ORDER follows `mine` (the total-order winner), with `theirs`-
- * only additions appended — positional merging is out of scope (fractional indexing is the
- * known upgrade if dogfooding demands it). Arrays still TRAVEL as whole-value sets; identity
- * only shapes conflict resolution, so the wire format is untouched.
+ * only additions appended, and arrays still TRAVEL as whole-value sets. For a list whose elements
+ * move and edit concurrently, model it as a keyed container (a record of elements ordered by
+ * `posBetween`) instead: `insertElement`/`moveElement`/`removeElement` write per element, so a
+ * reorder and a concurrent edit both survive and elements travel one at a time.
  */
 declare function keyedArray(identity: (item: unknown) => unknown, opt?: {
     item?: MergeFn;
 }): MergeFn;
+/**
+ * One retained concurrent write at a path. The register keeps at most one sibling per origin
+ * (a replica's newer op replaces its own older one) plus a per-origin supersession watermark,
+ * so state stays bounded by the concurrent-writer count, not the op count.
+ */
+type SyncSibling = {
+    readonly kind: 'set' | 'delete' | 'clear';
+    /** The written value for a `set`; absent for `delete`/`clear`. */
+    readonly value?: unknown;
+    /** The emitter's inversion hint, kept for value-merging folds; irrelevant to convergence. */
+    readonly prev?: unknown;
+    readonly writer: string;
+    readonly origin: string;
+    readonly hlc: Hlc;
+    readonly epoch: number;
+};
+/**
+ * What a fold decided for a path: a value to graft, a key removal, or `clear` (the register
+ * abstains and the value at that path comes from the nearest ancestor write instead).
+ */
+type FoldResult = {
+    readonly kind: 'set';
+    readonly value: unknown;
+} | {
+    readonly kind: 'delete';
+} | {
+    readonly kind: 'clear';
+};
+/**
+ * A conflict-resolution fold over the live sibling set of one path register. Called with the
+ * full set of causally-maximal concurrent writes; must be a pure function of that SET (never
+ * of arrival order); then the materialized value converges on every peer by construction.
+ *
+ * A custom fold MUST keep `epoch` as its outermost comparison (prefer max-epoch siblings
+ * unconditionally, as {@link compareSiblings} does). The epoch exists to retire stale values: a
+ * long-partitioned replica can resurface an old write that nothing ever cited, and without the
+ * epoch gate a fold that ranks it high would snap the value backwards. Folding a lower-epoch
+ * sibling's content into the result reopens exactly that hazard.
+ */
+type FoldFn = (siblings: readonly SyncSibling[], ctx: MergeContext) => FoldResult;
+type FoldPolicyEntry = {
+    /** `'todos.*.title'` or a segment array; `'*'` matches exactly one segment. */
+    readonly path: string | readonly Key[];
+    readonly fold: FoldFn;
+};
+/**
+ * The register's total order: max by `(epoch, kind-class, hlc, writer, origin)`, where `set`
+ * and `delete` outrank `clear` at equal epoch. Epoch first makes an authority bump decisive
+ * regardless of clocks (and closes stale-value resurrection); the kind-class tier makes a
+ * concurrent edit's survival of a subtree replace categorical rather than a clock race; origin
+ * last keeps the order strict when two replicas share a writer and a stamp.
+ */
+declare function compareSiblings(a: SyncSibling, b: SyncSibling): number;
+/** Last-writer-wins over the live sibling set: the {@link compareSiblings} maximum, as-is. */
+declare const defaultFold: FoldFn;
+/**
+ * Per-path register state, serializable: the live + superseded siblings and the per-origin
+ * supersession watermarks. This is what a snapshot ships, never a folded value: a
+ * joiner seeded with only a value cannot supersede or be superseded correctly afterwards.
+ */
+type RegisterCheckpoint = {
+    readonly path: readonly Key[];
+    readonly siblings: readonly SyncSibling[];
+    readonly water: Readonly<Record<string, Hlc>>;
+};
 type ConvergingApply = {
     /**
-     * Fold an envelope into the register map and return the ops the local store must apply
-     * (post-dominance, post-policy, including replays of newer descendant winners). Pass
-     * `local: true` for envelopes this peer emitted itself: registered, nothing returned.
+     * Fold an envelope into the per-path registers and return the materialization deltas the
+     * local store must apply: plain `set`/`delete` ops (never `clear`), `[]` when no fold
+     * winner changed. Pass `local: true` for envelopes this peer emitted itself: registered,
+     * nothing returned, unless `reconcile: true` is also set, which registers the op locally AND
+     * returns the fold delta (a fork commit lands as a concurrent sibling, so the store must move to
+     * the fold winner rather than the raw committed value). Pass `frontier` to reject ops at or below
+     * a pruned horizon, so a straggler older than compacted state can never resurrect.
      */
     ingest(env: OpEnvelope, opt?: {
         local?: boolean;
+        reconcile?: boolean;
+        frontier?: Hlc;
     }): StoreOp[];
-    /** Drop all registers (snapshot compaction / rehydration boundary). */
+    /**
+     * Stamp locally-diffed ops for emission: each op cites the live dots at its path and adopts
+     * `max(observed epoch, own prior epoch at the path)`, plus 1 per path when `bump` is set (an
+     * authority override). A `set`/`delete` at a path additionally expands into one `clear` per
+     * live descendant register (the observed-remove half of a subtree replace), so a concurrent
+     * descendant edit this replica never saw stays live and survives the replace. Pass `frontier` to
+     * cite only the siblings observed as of that point (a fork committing what it saw when it forked),
+     * so mid-flight writes stay concurrent instead of being superseded.
+     */
+    stamp(ops: readonly StoreOp[], opt?: {
+        bump?: boolean;
+        frontier?: DotFrontier;
+    }): SyncOp[];
+    /** Capture the current observation frontier, for later scoped emission; O(1). */
+    captureFrontier(): DotFrontier;
+    /** The live (causally-maximal) siblings at a path: the emission-frontier read. */
+    liveAt(path: readonly Key[]): readonly SyncSibling[];
+    /**
+     * Deepest-live-wins materialization of the whole tree from the current register state: the
+     * root register's fold value with every live descendant fold grafted on. This is what a
+     * replica's root reads after loading a checkpoint, so a joiner given only register state
+     * (never a folded value) can derive its root through its OWN fold configuration.
+     */
+    materialize(): unknown;
+    /** Serializable register state for a snapshot/seed checkpoint. */
+    checkpoint(): RegisterCheckpoint[];
+    /** Merge checkpointed register state in (idempotent; call after `reset()` on hydrate). */
+    load(registers: readonly RegisterCheckpoint[]): void;
+    /**
+     * Drop settled state at or below the stability frontier: superseded siblings and their
+     * watermarks, plus a register whose only live winner is a below-frontier tombstone once nothing
+     * else still materializes its key (no live descendant register, no live ancestor `set` value
+     * holding it), so state stays bounded under key churn. Never changes a fold above the frontier;
+     * pair with `ingest`'s `frontier` so pruned ops are rejected on re-delivery.
+     */
+    prune(frontier: Hlc): void;
+    /** Drop all registers (snapshot compaction / rehydration boundary). Emission epoch floors survive. */
     reset(): void;
 };
 /**
- * The unsequenced-topology convergence core: a per-path last-writer-wins
- * register map over the total order (hlc, writer), with subtree dominance. Order-independent:
- * any arrival order of the same envelope set yields the same state.
+ * The unsequenced-topology convergence core: a dot-citation multi-value register per path.
+ * An op supersedes exactly the sibling dots it cites; uncited concurrent writes stay live; a
+ * pluggable fold resolves the live set at read. Both the live set and any pure fold over it
+ * are functions of the delivered op SET, so any arrival order of the same envelopes (split,
+ * duplicated, cites-before-ops) yields the same state.
  */
 declare function createConvergingApply(opt?: {
     policies?: readonly MergePolicyEntry[];
+    /** Per-path custom folds; take precedence over the `policies` mapping. */
+    folds?: readonly FoldPolicyEntry[];
+    /** The local replica id: lets loaded checkpoints restore this replica's emission epoch floors. */
+    origin?: string;
 }): ConvergingApply;
 type RebaseResult<T = unknown> = {
     root: T;
@@ -3404,11 +3584,41 @@ type OpSyncOptions = {
     readonly origin?: string;
     readonly policyVersion?: number;
     readonly policies?: readonly MergePolicyEntry[];
+    /** Per-path custom register folds; take precedence over the `policies` mapping. */
+    readonly folds?: readonly FoldPolicyEntry[];
     readonly clock?: HlcClock;
     readonly injector?: Injector;
     readonly driver?: OpLogDriver;
     /** A version gap from a known origin (missed envelopes) — the resync hook. */
     readonly onGap?: (origin: string, expected: number, got: number) => void;
+    /** A received envelope rejected as malformed by {@link validateEnvelope}, with the reason. */
+    readonly onReject?: (env: OpEnvelope, reason: string) => void;
+};
+/**
+ * A peer-state checkpoint: the current root as the materialization base, the per-path register
+ * state (siblings + watermarks), and the per-origin version watermark. Register state rides
+ * along because a value alone is not enough to join a room: a peer hydrated from a bare value
+ * cannot tell a late straggler from a live concurrent write, so an already-superseded op would
+ * resurrect on it while every established peer keeps ignoring it.
+ */
+type OpSyncCheckpoint<T = unknown> = {
+    readonly root: T;
+    readonly registers: readonly RegisterCheckpoint[];
+    readonly wm: Readonly<Record<string, number>>;
+};
+/**
+ * A {@link Fork} of a synced store. Everything a plain fork does, plus `rebase()`. Committing it
+ * cites only the dots the fork observed when it was created (or last rebased), so an edit that
+ * landed on the base mid-flight stays a concurrent sibling and the configured fold decides between
+ * them; an approval click never silently discards a concurrent write.
+ */
+type SyncedFork<T> = Fork<T> & {
+    /**
+     * Re-observe the base: a following `commit()` cites the dots visible NOW, so the fork's edits
+     * supersede everything currently on the base (the reviewed-and-apply step). Keeps the staged
+     * edits; only advances what the next commit claims to have seen.
+     */
+    rebase(): void;
 };
 type OpSync<T = unknown> = {
     readonly origin: string;
@@ -3418,37 +3628,137 @@ type OpSync<T = unknown> = {
     receive(env: OpEnvelope): void;
     /** Synchronously emit any pending local delta now. */
     flush(): void;
+    /**
+     * Run `fn` and emit the writes it makes as authority-bumped ops: each written path gets
+     * epoch `max(observed at that path) + 1`, and a bumped subtree replace bumps every path it
+     * clears, so concurrent edits under it lose the fold instead of surviving. Scoped and
+     * synchronous: writes before/after emit normally. WHO may bump is admission policy at the
+     * transport/relay, not merge semantics; the register accepts any well-formed epoch.
+     */
+    override(fn: () => void): void;
+    /**
+     * Capture the current observation frontier: the set of writes this peer has seen right now, as a
+     * cheap marker. Pair with {@link commitScope} to emit later against what was observed then (the
+     * fork-commit seam); {@link syncedFork} wires both together.
+     */
+    captureFrontier(): DotFrontier;
+    /**
+     * Run `fn` and stamp the writes it makes against `frontier` rather than the current register
+     * state, so they cite only the siblings observed as of that frontier. A write against a stale
+     * frontier lands as a concurrent sibling (the fold decides) instead of superseding writes it
+     * never saw. Scoped and synchronous, like {@link override}.
+     */
+    commitScope(frontier: DotFrontier, fn: () => void): void;
     /** Per-origin latest versions — the handshake watermark. */
     watermark(): Record<string, number>;
-    /** The current root + watermark, for answering a peer's hello. */
-    snapshot(): {
-        root: T;
-        wm: Record<string, number>;
-    };
+    /** The full checkpoint (root + register state + watermark), for answering a peer's hello. */
+    snapshot(): OpSyncCheckpoint<T>;
     /**
-     * Emit the CURRENT root as a root-set envelope — the fresh-room seed of the relay
-     * contract (a room's snapshot root becomes complete once seeded).
+     * Emit the CURRENT root as a root-set envelope: the fresh-room seed of the relay contract.
+     * In a fresh room nothing was observed, so the op carries no cites and no clears; on a
+     * non-fresh instance it behaves as a whole-root replace (cites the root register's live
+     * dots and clears observed descendant registers).
      */
     seed(): void;
     /**
-     * Replace local state with a peer's snapshot, atomically (one notification wave).
-     * Local envelopes the snapshot doesn't cover (per its watermark) are re-applied on
-     * top, so writes made before hydration are never silently lost.
+     * Replace local state with a peer's checkpoint, atomically (one notification wave): adopt
+     * its root, load its register state, and fold its watermark. Local envelopes the checkpoint
+     * doesn't cover (per its watermark) are re-applied on top, so writes made before hydration
+     * are never silently lost; the next emitted version continues past the folded watermark.
+     * Pass `pending` (a durable outbox) to rebase from it instead of the bounded in-memory recent
+     * ring, so an offline burst larger than that ring is not dropped from the rebase.
      */
-    hydrate(root: T, wm?: Record<string, number>): void;
+    hydrate(state: OpSyncCheckpoint<T>, pending?: readonly OpEnvelope[]): void;
     /**
-     * Re-inject this origin's persisted local envelopes on boot (a durable outbox), WITHOUT minting
-     * new versions: each is applied to the store (echo-free), registered as a local winner, and handed
-     * to subscribers so a transport can resend the unacknowledged tail. `highWater` is the highest
-     * version this origin ever emitted (>= every `env.version`); the next mint continues past it, so a
-     * version acked before the reboot but dropped from a debounced outbox never collides. Call on a
-     * FRESH instance, before any `receive`/`hydrate` — restoring onto already-ingested remote winners
-     * would wrongly let a stale local op override them.
+     * Re-inject a persisted local outbox on boot, WITHOUT minting new versions: each envelope is
+     * applied to the store (echo-free), registered as a local winner, and handed to subscribers so a
+     * transport can resend the unacknowledged tail VERBATIM under its recorded origin (idempotent at
+     * receivers). Envelopes are accepted regardless of origin; their versions track per recorded
+     * origin. `highWater` is that origin's emit high-water (>= every `env.version`, including any acked
+     * then dropped from a debounced outbox), so a resent tail never re-mints below what the room may
+     * have sequenced. This instance mints on its OWN origin: pass a fresh per-boot origin and new
+     * writes start clean, so two clones of one outbox resend an identical tail (a duplicate) yet their
+     * new writes land on distinct origins and never collide. Call on a FRESH instance, before any
+     * `receive`/`hydrate` — restoring onto already-ingested remote winners would wrongly let a stale
+     * local op override them.
      */
     restore(envs: readonly OpEnvelope[], highWater?: number): void;
+    /**
+     * Reclaim settled register state at or below a stability frontier: superseded siblings, their
+     * watermarks, and lone tombstones nothing still materializes. Never changes the current value, so
+     * it is safe to call whenever a transport learns the frontier has advanced (a straggler below it
+     * is rejected at ingest, so nothing can resurrect). Without it, per-path register state grows with
+     * every path ever written; with it, state stays bounded by what is live above the frontier.
+     */
+    prune(frontier: Hlc): void;
     destroy(): void;
 };
 declare function opSync<T extends object>(source: WritableSignal<T>, opt: OpSyncOptions): OpSync<T>;
+/**
+ * Fork a synced store for isolated edits (an agent branch, a staged review), keeping the correct
+ * emission semantics on commit. The fork observes the base as it was when this call ran; committing
+ * emits its diff citing only those observed dots, so an edit that landed on the base mid-flight
+ * stays a concurrent sibling and the configured fold decides between them, rather than the commit
+ * overwriting a write it never saw. `rebase()` re-observes the base (a following commit then
+ * supersedes what is visible now, the reviewed-and-apply step). Pass the same `store` and `sync`
+ * that are wired together; the fork is a plain {@link Fork} otherwise, so `forkStore` itself stays
+ * sync-agnostic.
+ */
+declare function syncedFork<T extends Record<string, any>>(sync: OpSync, store: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): SyncedFork<T>;
+
+/**
+ * Reserved key holding an element's fractional position inside a keyed container. It lives INSIDE
+ * the element (at `[container, elementKey, '~pos']`), so a reorder is a one-field write that never
+ * collides with a concurrent edit to the element's data. It stays visible on the materialized
+ * element value; do not read, write, or strip it by hand, use the helpers in this file.
+ */
+declare const POS_SEGMENT = "~pos";
+/**
+ * A compact position string strictly between `before` and `after`, ordered by plain string
+ * comparison. Pass `undefined` for an open end: `posBetween()` seeds the first element,
+ * `posBetween(last)` appends, `posBetween(undefined, first)` prepends. Repeated inserts into the
+ * same gap grow the string one digit at a time rather than colliding, and the result is never equal
+ * to either neighbor. `before` must sort before `after`.
+ */
+declare function posBetween(before?: string, after?: string): string;
+/** An element of a keyed container in reading order: its key, its position, and its value. */
+type OrderedEntry<T> = {
+    readonly key: string;
+    readonly pos: string;
+    readonly value: T;
+};
+/**
+ * A keyed container's elements in reading order. Order is a pure function of the materialized
+ * value: elements sort by their `~pos` string, ties broken by key. An element whose `~pos` is
+ * missing or not a string is ordered as if its position were the empty string (it sorts first,
+ * key breaking the tie), so a peer that dropped the position field still lands somewhere
+ * deterministic on every replica.
+ */
+declare function orderedEntries<T>(container: Record<string, T>): OrderedEntry<T>[];
+/** A store node (or plain writable signal) holding a keyed container: a RECORD keyed by element id. */
+type ContainerNode<T> = WritableSignal<Record<string, T>>;
+/**
+ * Insert `value` under `key` at `index` in reading order (default: append). The position is
+ * computed from the neighbors at that index, so the element lands where asked without renumbering
+ * any sibling. A keyed container is a RECORD, never an array, so this is a per-key write the sync
+ * layer diffs on its own. Returns the assigned position. Re-inserting an existing key overwrites it.
+ */
+declare function insertElement<T extends object>(container: ContainerNode<T>, key: string, value: T, index?: number): string;
+/**
+ * Move the element at `key` to `index` in reading order. This writes ONLY the element's `~pos`
+ * field, so it never conflicts with a concurrent edit to the same element's data (they land on
+ * different paths and both survive). Returns the new position, or `undefined` if `key` is absent.
+ */
+declare function moveElement<T extends object>(container: ContainerNode<T>, key: string, index: number): string | undefined;
+/** Remove the element at `key`. Deletes the whole element (a per-key delete the sync layer folds). */
+declare function removeElement<T>(container: ContainerNode<T>, key: string): void;
+/**
+ * Reassign every element's position to a fresh, evenly spaced sequence, as an authority write:
+ * each `~pos` set is epoch-bumped so it wins the merge against any concurrent move, while leaving
+ * concurrent edits to element DATA untouched (only the `~pos` fields are written). Use this to
+ * reclaim precision after many same-gap inserts. Existing reading order is preserved.
+ */
+declare function rebalanceContainer<T extends object>(sync: Pick<OpSync, 'override'>, container: ContainerNode<T>): void;
 
 type StoreHistory = {
     readonly canUndo: Signal<boolean>;
@@ -3457,6 +3767,12 @@ type StoreHistory = {
     undo(): void;
     /** Re-apply the most recently undone change. */
     redo(): void;
+    /**
+     * Close the current coalescing run: the next tracked change starts a NEW undo entry even if
+     * it lands inside the `coalesce` window. Call it on the boundaries your UX considers an
+     * action — a field blur, a selection change, a drag drop. A no-op without `coalesce`.
+     */
+    checkpoint(): void;
     /** Forget all tracked history (e.g. after a save boundary). */
     clear(): void;
     destroy(): void;
@@ -3468,11 +3784,29 @@ type StoreHistoryOptions = CreateOpLogOptions & {
      * The change stream to track. Defaults to self-diffing `source` (every change to the store
      * becomes undoable). For collaborative-safe undo, pass a sync client's LOCAL envelope stream
      * (e.g. an `opSync`'s `subscribe`, which fires only for this peer's own writes) — remote
-     * peers' changes then never land on your undo stack.
+     * peers' changes then never land on your undo stack. When the stream exposes `flush` (an
+     * `opSync` does), undo/redo drain it synchronously so their own emissions never echo back
+     * onto the stack as fresh entries.
      */
     readonly track?: {
         subscribe(cb: (batch: OpBatch) => void): () => void;
+        flush?(): void;
+    };
+    /**
+     * Merge rapid consecutive edits into ONE undo entry, so a typing run undoes as a unit
+     * instead of per keystroke. A tracked change arriving within `ms` of the previous one AND
+     * touching the same paths with the same op kinds extends the previous entry (set
+     * `samePath: false` to merge on time alone); anything else — a different field, a kind
+     * change, a pause longer than `ms`, a `checkpoint()`, an undo/redo — starts a new entry.
+     * The window is measured between consecutive changes, so an unbroken run keeps merging.
+     * Undoing a merged entry is exactly equivalent to undoing its changes one by one.
+     */
+    readonly coalesce?: {
+        readonly ms: number;
+        readonly samePath?: boolean;
     };
+    /** Clock for the coalescing window (injectable for tests; default `Date.now`). */
+    readonly now?: () => number;
 };
 /**
  * Undo/redo for a copy-on-write store, built on the op-log: each tracked change is stored as
@@ -3482,7 +3816,8 @@ type StoreHistoryOptions = CreateOpLogOptions & {
  *
  * Composes with sync for collaborative undo: pass `track: syncClient` so only YOUR writes are
  * undoable, while `undo()` emits a normal op that propagates to peers (it writes through the
- * store, which the sync client picks up).
+ * store, which the sync client picks up). Coalescing groups only this stack's entries — what
+ * goes over the wire is untouched.
  */
 declare function storeHistory<T extends object>(source: WritableSignal<T>, opt?: StoreHistoryOptions): StoreHistory;
 
@@ -4146,5 +4481,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebaseOps, reconcile, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
-export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncOptions, Opaque, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncSignalOptions, TabSyncBus, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, POS_SEGMENT, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareSiblings, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, defaultFold, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, insertElement, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, moveElement, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orderedEntries, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, posBetween, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebalanceContainer, rebaseOps, reconcile, registerResource, removeElement, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, syncedFork, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, validateEnvelope, windowSize, withHistory };
+export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ContainerNode, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, Dot, DotFrontier, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, FoldFn, FoldPolicyEntry, FoldResult, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncCheckpoint, OpSyncOptions, Opaque, OrderedEntry, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterCheckpoint, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncOp, SyncSibling, SyncSignalOptions, SyncedFork, TabSyncBus, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };