@lazily-hub/lazily-js 0.4.0

package/src/sem-tree.js

@@ -0,0 +1,130 @@
+// Memoized semantic tree (cell-model.md § Memoized semantic tree, #lzsemtree).
+// One memo slot per node folds (node value, child derived values). Editing one
+// node recomputes only its ANCESTOR CHAIN — a sibling subtree's derived slot
+// stays cached (incremental, glitch-free). A node edit that does not change
+// the folded result MUST NOT re-run a downstream consumer (memo equality guard).
+// Cost is proportional to the diff, not the document.
+//
+// The tree is reactive: each node's value is a `Cell` and its child list is a
+// `Cell`, so a SemTree composes over the owning `Context`. Structural growth
+// (inserting a brand-new child) requires `build` again (the captured child-slot
+// map is fixed at build time, per the lazily-rs/lazily-kt contract); removals
+// are covered by incrementality because the parent's child-list cell changes.
+
+import { Context, SlotHandle } from "./reactive.js";
+
+class SemNode {
+  constructor(id, value, ctx) {
+    this.id = id;
+    this.valueCell = ctx.cell(value);
+    this.childKeysCell = ctx.cell([]); // array of child ids (reactive membership/order)
+    this.childSlots = new Map(); // child id -> SlotHandle (captured at build)
+    this.slot = null; // memo SlotHandle for this node's derived value
+  }
+}
+
+export class SemTree {
+  #ctx;
+  #nodes = new Map(); // id -> SemNode
+  #rootId;
+  #fold;
+
+  constructor(ctx, rootSpec, fold) {
+    this.#ctx = ctx;
+    this.#fold = fold;
+    this.#rootId = rootSpec.id;
+    this.#build(rootSpec);
+  }
+
+  static build(ctx, rootSpec, fold) {
+    return new SemTree(ctx, rootSpec, fold);
+  }
+
+  #build(spec) {
+    const node = new SemNode(spec.id, spec.value, this.#ctx);
+    this.#nodes.set(spec.id, node);
+    const childOrder = [];
+    const children = (spec.children && spec.children.values) ?? {};
+    const order = (spec.children && spec.children.order) ?? Object.keys(children);
+    for (const childKey of order) {
+      const childSpec = children[childKey];
+      if (!childSpec) {
+        continue;
+      }
+      const childNode = this.#build(childSpec);
+      childOrder.push(childSpec.id);
+      node.childSlots.set(childSpec.id, childNode.slot);
+    }
+    // Set the child-list cell BEFORE registering the memo so the memo observes it.
+    this.#ctx.setCell(node.childKeysCell, childOrder);
+    // Register the memo slot: subscribes to own value cell, own child-list cell,
+    // and each present child's derived slot.
+    const ctx = this.#ctx;
+    const fold = this.#fold;
+    const self = this;
+    node.slot = ctx.memo(() => {
+      const v = ctx.getCell(node.valueCell);
+      const kids = ctx.getCell(node.childKeysCell);
+      const ds = [];
+      for (const kid of kids) {
+        const childSlot = node.childSlots.get(kid);
+        if (childSlot) {
+          ds.push(ctx.get(childSlot));
+        }
+      }
+      return fold(v, ds);
+    });
+    return node;
+  }
+
+  // Edit a node's value cell. Only the ancestor chain recomputes.
+  setValue(id, value) {
+    const node = this.#nodes.get(id);
+    if (!node) {
+      throw new RangeError(`SemTree node not present: ${String(id)}`);
+    }
+    this.#ctx.setCell(node.valueCell, value);
+  }
+
+  // Remove a child from its parent's child-list cell. The parent re-folds over
+  // the remaining children (covered by incrementality).
+  removeChild(parentId, childId) {
+    const parent = this.#nodes.get(parentId);
+    if (!parent) {
+      throw new RangeError(`SemTree parent not present: ${String(parentId)}`);
+    }
+    const kids = this.#ctx.getCell(parent.childKeysCell).filter((k) => k !== childId);
+    this.#ctx.setCell(parent.childKeysCell, kids);
+  }
+
+  // Reactive read of the root derived value.
+  value() {
+    return this.#ctx.get(this.#nodes.get(this.#rootId).slot);
+  }
+
+  // Reactive read at a node id.
+  nodeValue(id) {
+    const node = this.#nodes.get(id);
+    if (!node) {
+      return undefined;
+    }
+    return this.#ctx.get(node.slot);
+  }
+
+  // Whether a node's derived slot currently has a fresh cached value (testing).
+  isCached(id) {
+    const node = this.#nodes.get(id);
+    if (!node) {
+      return false;
+    }
+    return this.#ctx.isSet(node.slot);
+  }
+
+  rootHandle() {
+    return this.#nodes.get(this.#rootId).slot;
+  }
+
+  nodeHandle(id) {
+    return this.#nodes.get(id)?.slot ?? null;
+  }
+}

package/src/seq-crdt.d.ts

@@ -0,0 +1,44 @@
+export class HlcStamp {
+  readonly wallTime: number;
+  readonly logical: number;
+  readonly peer: number;
+  constructor(wallTime: number, logical: number, peer: number);
+  compareTo(other: HlcStamp): number;
+  static max(a: HlcStamp, b: HlcStamp): HlcStamp;
+}
+
+export class Hlc {
+  constructor(peer: number);
+  send(nowMicros: number): HlcStamp;
+  recv(remote: HlcStamp, nowMicros: number): HlcStamp;
+}
+
+export class Position {
+  readonly frac: number[];
+  readonly peer: number;
+  constructor(frac: number[], peer: number);
+  compareTo(other: Position): number;
+}
+
+export class SeqCrdt<Id, V> {
+  constructor(peer: number);
+  insertBetween(id: Id, value: V, left: Id | null, right: Id | null, nowMicros: number): void;
+  insertBack(id: Id, value: V, nowMicros: number): void;
+  insertFront(id: Id, value: V, nowMicros: number): void;
+  setValue(id: Id, value: V, nowMicros: number): boolean;
+  moveBetween(id: Id, left: Id | null, right: Id | null, nowMicros: number): boolean;
+  moveAfter(id: Id, anchor: Id, nowMicros: number): boolean;
+  moveBefore(id: Id, anchor: Id, nowMicros: number): boolean;
+  remove(id: Id, nowMicros: number): boolean;
+  contains(id: Id): boolean;
+  get(id: Id): V | undefined;
+  order(): Id[];
+  values(): Array<[Id, V]>;
+  tombstoneCount(): number;
+  fork(peer: number): SeqCrdt<Id, V>;
+  clone(): SeqCrdt<Id, V>;
+  merge(other: SeqCrdt<Id, V>, nowMicros: number): boolean;
+  gcWith(isStable: (stamp: HlcStamp) => boolean): number;
+  gc(watermark: HlcStamp): number;
+  entryCount(): number;
+}

package/src/seq-crdt.js

@@ -0,0 +1,364 @@
+// Move-aware sequence CRDT (cell-model.md § Move-aware sequence order,
+// #lzseqcrdt). Each element is three independent LWW registers — value,
+// position (fractional-index byte key + peer), deleted — each stamped by an
+// HLC. A move is a SINGLE LWW reassignment of the position register (not
+// delete + reinsert), so concurrent moves of the same element converge to the
+// later stamp without duplication; a concurrent move + value-edit both apply
+// (independent registers). Removal is an LWW tombstone. Order is the
+// lexicographic total order on (frac, peer).
+
+// Hybrid logical clock stamp: total order is (wall_time, logical, peer).
+export class HlcStamp {
+  constructor(wallTime, logical, peer) {
+    this.wallTime = wallTime;
+    this.logical = logical;
+    this.peer = peer;
+    Object.freeze(this);
+  }
+  compareTo(other) {
+    if (this.wallTime !== other.wallTime) {
+      return this.wallTime < other.wallTime ? -1 : 1;
+    }
+    if (this.logical !== other.logical) {
+      return this.logical < other.logical ? -1 : 1;
+    }
+    if (this.peer !== other.peer) {
+      return this.peer < other.peer ? -1 : 1;
+    }
+    return 0;
+  }
+  static max(a, b) {
+    return a.compareTo(b) >= 0 ? a : b;
+  }
+}
+
+// HLC: guarantees strictly-increasing stamps on a given peer.
+export class Hlc {
+  constructor(peer) {
+    this.peer = peer;
+    this.lastWall = 0;
+    this.lastLogical = 0;
+  }
+  send(nowMicros) {
+    if (nowMicros > this.lastWall) {
+      this.lastWall = nowMicros;
+      this.lastLogical = 0;
+    } else {
+      this.lastLogical += 1;
+    }
+    return new HlcStamp(this.lastWall, this.lastLogical, this.peer);
+  }
+  // Observe a remote stamp, advancing the local clock past it (return value
+  // unused by SeqCrdt.merge — only the side effect matters).
+  recv(remote, nowMicros) {
+    const wall = Math.max(this.lastWall, remote.wallTime, nowMicros);
+    if (wall === this.lastWall && wall === remote.wallTime) {
+      this.lastLogical = Math.max(this.lastLogical, remote.logical) + 1;
+    } else if (wall === this.lastWall) {
+      this.lastLogical += 1;
+    } else if (wall === remote.wallTime) {
+      this.lastLogical = remote.logical + 1;
+    } else {
+      this.lastLogical = 0;
+    }
+    this.lastWall = wall;
+    return new HlcStamp(this.lastWall, this.lastLogical, this.peer);
+  }
+}
+
+// LWW register: overwrite iff stamp is STRICTLY > current (incumbent wins ties).
+export class LwwRegister {
+  constructor(value, stamp) {
+    this.value = value;
+    this.stamp = stamp;
+  }
+  set(value, stamp) {
+    if (stamp.compareTo(this.stamp) > 0) {
+      this.value = value;
+      this.stamp = stamp;
+      return true;
+    }
+    return false;
+  }
+  // Merge from another register: take other's (value, stamp) iff strictly newer.
+  // Returns true iff the VALUE changed.
+  mergeFrom(other) {
+    if (other.stamp.compareTo(this.stamp) > 0) {
+      const changed = !valuesEqual(this.value, other.value);
+      this.value = other.value;
+      this.stamp = other.stamp;
+      return changed;
+    }
+    return false;
+  }
+}
+
+function valuesEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a instanceof Position && b instanceof Position) {
+    return a.compareTo(b) === 0;
+  }
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+    return a === b;
+  }
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+// Position: fractional-index byte key + originating peer.
+export class Position {
+  constructor(frac, peer) {
+    this.frac = frac; // number[] (bytes 0..255)
+    this.peer = peer;
+    Object.freeze(this);
+  }
+  compareTo(other) {
+    const len = Math.min(this.frac.length, other.frac.length);
+    for (let i = 0; i < len; i++) {
+      if (this.frac[i] !== other.frac[i]) {
+        return this.frac[i] < other.frac[i] ? -1 : 1;
+      }
+    }
+    if (this.frac.length !== other.frac.length) {
+      return this.frac.length < other.frac.length ? -1 : 1;
+    }
+    if (this.peer !== other.peer) {
+      return this.peer < other.peer ? -1 : 1;
+    }
+    return 0;
+  }
+}
+
+// Fractional-index midpoint: a key strictly between lo and hi (exclusive).
+// Append-only — positions grow under repeated subdivision, never rebalanced.
+function keyBetween(lo, hi) {
+  const result = [];
+  const cap = (lo ? lo.length : 0) + (hi ? hi.length : 0) + 2;
+  let i = 0;
+  while (i <= cap) {
+    const a = lo && i < lo.length ? lo[i] : 0;
+    const b = hi === null ? 256 : i < hi.length ? hi[i] : 0;
+    if (a + 1 < b) {
+      result.push(Math.floor((a + b) / 2));
+      return result;
+    }
+    result.push(a);
+    i++;
+    if (a < b) {
+      // Dropped strictly below hi: descend with open top.
+      const loTail = lo ? lo.slice(i) : [];
+      result.push(...keyBetween(loTail.length > 0 ? loTail : null, null));
+      return result;
+    }
+    // a === b: shared prefix, continue.
+  }
+  result.push(128);
+  return result;
+}
+
+class Entry {
+  constructor(value, position, deleted) {
+    this.value = value; // LwwRegister<V>
+    this.position = position; // LwwRegister<Position>
+    this.deleted = deleted; // LwwRegister<bool>
+  }
+  clone() {
+    return new Entry(
+      new LwwRegister(this.value.value, this.value.stamp),
+      new LwwRegister(this.position.value, this.position.stamp),
+      new LwwRegister(this.deleted.value, this.deleted.stamp),
+    );
+  }
+  maxStamp() {
+    let max = this.value.stamp;
+    if (this.position.stamp.compareTo(max) > 0) max = this.position.stamp;
+    if (this.deleted.stamp.compareTo(max) > 0) max = this.deleted.stamp;
+    return max;
+  }
+}
+
+export class SeqCrdt {
+  #entries = new Map();
+  #hlc;
+  #peer;
+
+  constructor(peer) {
+    this.#peer = peer;
+    this.#hlc = new Hlc(peer);
+  }
+
+  #fracOf(id) {
+    const e = this.#entries.get(id);
+    return e ? [...e.position.value.frac] : undefined;
+  }
+
+  insertBetween(id, value, left, right, nowMicros) {
+    if (this.#entries.has(id)) {
+      return; // no-op if already present (use moveBetween to relocate)
+    }
+    const lo = left !== null && left !== undefined ? this.#fracOf(left) : undefined;
+    const hi = right !== null && right !== undefined ? this.#fracOf(right) : undefined;
+    const frac = keyBetween(lo ?? null, hi ?? null);
+    const pos = new Position(frac, this.#peer);
+    const stamp = this.#hlc.send(nowMicros);
+    this.#entries.set(id, new Entry(
+      new LwwRegister(value, stamp),
+      new LwwRegister(pos, stamp),
+      new LwwRegister(false, stamp),
+    ));
+  }
+
+  insertBack(id, value, nowMicros) {
+    const order = this.order();
+    const left = order.length > 0 ? order[order.length - 1] : null;
+    this.insertBetween(id, value, left, null, nowMicros);
+  }
+
+  insertFront(id, value, nowMicros) {
+    const order = this.order();
+    const right = order.length > 0 ? order[0] : null;
+    this.insertBetween(id, value, null, right, nowMicros);
+  }
+
+  setValue(id, value, nowMicros) {
+    const e = this.#entries.get(id);
+    if (!e) {
+      return false;
+    }
+    return e.value.set(value, this.#hlc.send(nowMicros));
+  }
+
+  moveBetween(id, left, right, nowMicros) {
+    const e = this.#entries.get(id);
+    if (!e) {
+      return false;
+    }
+    const lo = left !== null && left !== undefined ? this.#fracOf(left) : undefined;
+    const hi = right !== null && right !== undefined ? this.#fracOf(right) : undefined;
+    const frac = keyBetween(lo ?? null, hi ?? null);
+    const pos = new Position(frac, this.#peer);
+    e.position.set(pos, this.#hlc.send(nowMicros));
+    return true;
+  }
+
+  moveAfter(id, anchor, nowMicros) {
+    const order = this.order();
+    const idx = order.indexOf(anchor);
+    if (idx === -1) {
+      return false;
+    }
+    const right = idx + 1 < order.length ? order[idx + 1] : null;
+    return this.moveBetween(id, anchor, right, nowMicros);
+  }
+
+  moveBefore(id, anchor, nowMicros) {
+    const order = this.order();
+    const idx = order.indexOf(anchor);
+    if (idx === -1) {
+      return false;
+    }
+    const left = idx > 0 ? order[idx - 1] : null;
+    return this.moveBetween(id, left, anchor, nowMicros);
+  }
+
+  remove(id, nowMicros) {
+    const e = this.#entries.get(id);
+    if (!e) {
+      return false;
+    }
+    return e.deleted.set(true, this.#hlc.send(nowMicros));
+  }
+
+  contains(id) {
+    const e = this.#entries.get(id);
+    return e !== undefined && !e.deleted.value;
+  }
+
+  get(id) {
+    const e = this.#entries.get(id);
+    return e && !e.deleted.value ? e.value.value : undefined;
+  }
+
+  order() {
+    const live = [];
+    for (const [id, e] of this.#entries) {
+      if (!e.deleted.value) {
+        live.push([id, e.position.value]);
+      }
+    }
+    live.sort((a, b) => a[1].compareTo(b[1]));
+    return live.map(([id]) => id);
+  }
+
+  values() {
+    return this.order().map((id) => [id, this.get(id)]);
+  }
+
+  tombstoneCount() {
+    let count = 0;
+    for (const e of this.#entries.values()) {
+      if (e.deleted.value) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  // Deep-copy entries, mint a fresh Hlc for a new peer (stamps live in registers).
+  fork(peer) {
+    const copy = new SeqCrdt(peer);
+    for (const [id, e] of this.#entries) {
+      copy.#entries.set(id, e.clone());
+    }
+    return copy;
+  }
+
+  clone() {
+    return this.fork(this.#peer);
+  }
+
+  // State-based merge: advance clock past everything observed, then per-element
+  // three-way LWW merge over each independent register. Returns whether anything
+  // changed. Commutative, associative, idempotent.
+  merge(other, nowMicros) {
+    for (const e of other.#entries.values()) {
+      this.#hlc.recv(e.maxStamp(), nowMicros);
+    }
+    let changed = false;
+    for (const [id, oe] of other.#entries) {
+      const existing = this.#entries.get(id);
+      if (existing) {
+        changed = existing.value.mergeFrom(oe.value) || changed;
+        changed = existing.position.mergeFrom(oe.position) || changed;
+        changed = existing.deleted.mergeFrom(oe.deleted) || changed;
+      } else {
+        this.#entries.set(id, oe.clone());
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  // Tombstone GC: collect entries where deleted == true AND the delete stamp is
+  // causally stable (caller-supplied policy). Observationally inert: order() and
+  // contains() already skip tombstones.
+  gcWith(isStable) {
+    const before = this.#entries.size;
+    for (const [id, e] of this.#entries) {
+      if (e.deleted.value && isStable(e.deleted.stamp)) {
+        this.#entries.delete(id);
+      }
+    }
+    return before - this.#entries.size;
+  }
+
+  gc(watermark) {
+    return this.gcWith((s) => s.compareTo(watermark) <= 0);
+  }
+
+  // Test/fixture access to the internal entry map.
+  entryCount() {
+    return this.#entries.size;
+  }
+}

package/src/stable-id.d.ts

@@ -0,0 +1,45 @@
+export const EDIT_THRESHOLD: 0.5;
+export const ANCHOR_PREFIX: "a:";
+export const CONTENT_PREFIX: "c:";
+
+export class Block {
+  readonly text: string;
+  readonly anchor: string | null;
+  constructor(text: string, anchor?: string | null);
+  static text(text: string): Block;
+  static anchored(anchor: string, text: string): Block;
+}
+
+export class BlockKey {
+  readonly kind: "anchored" | "content";
+  readonly value: string | bigint;
+  readonly isAnchored: boolean;
+  readonly isContent: boolean;
+  constructor(kind: "anchored" | "content", value: string | bigint);
+  equals(other: BlockKey): boolean;
+  asString(): string;
+}
+
+export function normalize(text: string): string;
+export function contentHash(text: string): bigint;
+export function blockKey(block: Block): BlockKey;
+export function similarity(a: string, b: string): number;
+
+export class Match {
+  readonly kind: "same" | "edited" | "inserted";
+  readonly oldIndex: number;
+  readonly similarity: number;
+  constructor(kind: "same" | "edited" | "inserted", oldIndex?: number, similarity?: number);
+  static same(oldIndex: number): Match;
+  static edited(oldIndex: number, similarity: number): Match;
+  static inserted(): Match;
+}
+
+export class Alignment {
+  readonly newMatches: Match[];
+  readonly removed: number[];
+  constructor(newMatches: Match[], removed: number[]);
+}
+
+export function align(oldBlocks: Block[], newBlocks: Block[]): Alignment;
+export function assignStableKeys(oldBlocks: Block[], newBlocks: Block[]): string[];