@lazily-hub/lazily-js 0.4.0 → 0.6.1

package/.github/workflows/release.yml

@@ -24,6 +24,15 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          path: lazily-js
+
+      # The conformance / schema tests replay fixtures from the lazily-spec sibling
+      # (../lazily-spec). Check it out alongside so `npm test` passes in CI.
+      - uses: actions/checkout@v4
+        with:
+          repository: lazily-hub/lazily-spec
+          path: lazily-spec
 
       - uses: actions/setup-node@v4
         with:
@@ -35,9 +44,11 @@ jobs:
         run: npm install -g npm@latest
 
       - name: Install dependencies
+        working-directory: lazily-js
         run: npm ci || npm install
 
       - name: Test
+        working-directory: lazily-js
         run: npm test --if-present
 
       # Published under the `prev` dist-tag so this v0.x line does not steal
@@ -45,4 +56,14 @@ jobs:
       # (`npm dist-tag add @lazily-hub/lazily-js@<v> latest`) once the accidental
       # v1.x releases are removed.
       - name: Publish
-        run: npm publish --access public --tag prev
+        working-directory: lazily-js
+        run: |
+          version="$(node -p "require('./package.json').version")"
+          if npm publish --access public --tag prev; then
+            echo "published @lazily-hub/lazily-js@${version}"
+          elif npm view "@lazily-hub/lazily-js@${version}" version >/dev/null 2>&1; then
+            echo "@lazily-hub/lazily-js@${version} already published — idempotent no-op"
+          else
+            echo "publish failed for a reason other than already-published" >&2
+            exit 1
+          fi

package/BENCHMARKS.md

@@ -0,0 +1,91 @@
+# lazily-js Benchmark Results
+
+Generated benchmark data for the
+[`@lazily-hub/lazily-js`](https://www.npmjs.com/package/@lazily-hub/lazily-js)
+reactive primitives library.
+
+## Benchmark Results
+
+The suite is a 1:1 port of the single-threaded `Context` benchmarks in
+lazily-rs's `benches/context.rs` — the same group/case names and the same
+widths/depths (`FAN_OUT_WIDTHS=[32,256]`, `MEMO_CHAIN_DEPTH=32`,
+`BATCH_STORM_CELLS=64`, `SET_CELL_INVALIDATION_FAN_OUT=512`) so JS and Rust
+numbers are directly comparable.
+
+JS runs on a single event-loop thread, so the lazily-rs `ThreadSafeContext`
+multi-worker contention benchmarks (`thread_safe_contention`,
+`thread_safe_effect_contention`, `thread_safe_graph_propagation`) have no
+like-for-like single-process counterpart here and are intentionally omitted.
+
+<!-- benchmark-results:start -->
+
+Generated for package `@lazily-hub/lazily-js` version `0.6.0`.
+
+Environment: Node.js `26.4.0` on `linux x64`.
+
+Refresh command:
+
+```bash
+node scripts/run-benchmarks.mjs
+```
+
+Mean wall-clock time per iteration; 95% CI half-width from the standard error.
+
+| Group | Case | Mean | 95% CI | p75 | p99 | Samples |
+|---|---|---:|---:|---:|---:|---:|
+| cached_reads | context | 57.798 ns | ± 20.941 ns | 46.398 ns | 124.744 ns | 100 |
+| cold_first_get | context | 669.220 ns | ± 8.630 ns | 670.000 ns | 802.610 ns | 100 |
+| dependency_fan_out | context / 32 | 7.448 us | ± 824.968 ns | 6.783 us | 34.205 us | 100 |
+| dependency_fan_out | context / 256 | 43.766 us | ± 1.064 us | 43.270 us | 49.513 us | 100 |
+| set_cell_invalidation | high_fan_out / 512 | 10.737 us | ± 376.524 ns | 10.113 us | 17.141 us | 100 |
+| memo_equality_suppression | context | 2.387 us | ± 193.801 ns | 2.310 us | 2.864 us | 100 |
+| effect_flushing | context | 211.187 ns | ± 20.150 ns | 221.482 ns | 524.491 ns | 100 |
+| batch_storms | context / 64 | 30.430 us | ± 1.295 us | 30.815 us | 49.775 us | 99 |
+| typed_cache_reads | context_cell | 31.325 ns | ± 1.052 ns | 30.255 ns | 58.102 ns | 100 |
+| typed_cache_reads | context_slot | 120.262 ns | ± 4.805 ns | 118.099 ns | 220.409 ns | 100 |
+
+<!-- benchmark-results:end -->
+
+## Suite
+
+| Group | Case | Parity with lazily-rs | What it measures |
+|-------|------|-----------------------|------------------|
+| `cached_reads` | `context` | `bench_cached_reads` / context | Steady-state cached `ctx.get(slot)` (no recompute). |
+| `cold_first_get` | `context` | `bench_cold_first_get` / context | First (uncached) read of a freshly built slot. |
+| `dependency_fan_out` | `context / {32,256}` | `bench_dependency_fan_out` / context | One root cell invalidates N dependents, then all are re-read. |
+| `set_cell_invalidation` | `high_fan_out / 512` | `bench_set_cell_invalidation` / high_fan_out | Cost of `setCell` invalidating a 512-wide fan-out (no recompute). |
+| `memo_equality_suppression` | `context` | `bench_memo_equality_suppression` / context | Memo chain that stays equal downstream (guard suppresses recompute). |
+| `effect_flushing` | `context` | `bench_effect_flushing` / context | Effect re-runs on every cell change. |
+| `batch_storms` | `context / 64` | `bench_batch_storms` / context | Coalesced batched writes to 64 cells (one effect flush). |
+| `typed_cache_reads` | `context_slot`, `context_cell` | `bench_typed_cache_reads` / context_* | Direct `ctx.get(slot)` vs `ctx.getCell(cell)`. |
+
+### Running
+
+```bash
+npm run bench                 # run the suite, print a markdown table
+node scripts/run-benchmarks.mjs        # run + refresh this file
+node scripts/run-benchmarks.mjs --check # CI gate: exit 1 if stale
+make bench                   # via the Makefile
+```
+
+### Harness
+
+`bench/harness.mjs` is a zero-dependency criterion-style harness
+(`node:perf_hooks` only). It offers two measurement modes:
+
+- **`bench(group, case, fn)`** — auto-batched timing for *idempotent* routines
+  (each sample times N calls, N auto-scaled so one sample lasts ~5 ms). Use for
+  steady-state reads / repeated-equal-cost work.
+- **`bench.batched(group, case, setup, routine)`** — `iter_batched` timing
+  (criterion `BatchSize::SmallInput`): fresh `setup()` before every single
+  measured call, setup excluded from timing. Use when the operation mutates graph
+  state a second call would skip — e.g. the `==` guard on `setCell`, or a cold
+  first read that caches on first access.
+
+### Regression workflow
+
+```bash
+node scripts/run-benchmarks.mjs            # record "before" baseline in BENCHMARKS.md
+# apply the performance patch
+node scripts/run-benchmarks.mjs            # compare against the new numbers
+```

package/README.md

@@ -6,6 +6,9 @@ is the JavaScript/TypeScript binding alongside [`lazily-rs`][rs],
 [`lazily-dart`][dart]. It ships:
 
 - a full reactive graph (`Context`, `Cell`, `Slot`, `Signal`, `Effect`);
+- an async reactive graph (`AsyncContext`) for Promise-driven derivations, with
+  revision-guarded stale-completion discard, in-flight deduplication, and
+  cancellation;
 - the [`lazily-spec`][spec] IPC wire types (`Snapshot`, `Delta`, `CrdtSync`,
   capability negotiation, and default-deny peer permissions);
 - keyed cell collections, move-minimized reconciliation, and a memoized
@@ -13,6 +16,9 @@ is the JavaScript/TypeScript binding alongside [`lazily-rs`][rs],
 - move-aware sequence CRDT, Fugue/RGA text CRDT, and manufactured text identity;
 - a Cell-backed flat state machine plus a full Harel/SCXML state-chart
   interpreter with the typed `ChartBuilder` API;
+- the distributed plane — the WebSocket signaling protocol + client, a
+  `DataChannel` transport seam with permission-filtering sink/source, a browser
+  `RTCPeerConnection` adapter, and the `CrdtPlaneRuntime` anti-entropy engine;
 - a koffi-backed state-projection consumer for agent-doc host projections.
 
 > **Package note.** Earlier `@lazily-hub/js` releases were only a state-projection
@@ -24,26 +30,42 @@ the FFI projection transport is used.
 
 ## Feature Set
 
-The full `lazily` capability set and its cross-language coverage (`lazily-rs`,
-`lazily-kt`, `lazily-js`). `✅` shipped, `~` partial, `—` not applicable/absent.
-
-| Feature | Rust | Kotlin | JS |
-|---------|:----:|:------:|:--:|
-| Reactive graph — `Context`, `Slot`, `Cell`, `memo`, `Signal` (eager), `Effect`, `batch` | ✅ | ✅ | ✅ |
-| Thread-safe `Context` (`Send + Sync`, lock-backed) | ✅ | ✅ | — |
-| Async reactive `Context` | ✅ | ✅ | — |
-| Statechart (Harel) + state machine | ✅ | ✅ | ✅ |
-| Keyed cell collections + `reconcile` + `SemTree` (keyed tree) | ✅ | ✅ | ✅ |
-| Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ |
-| Free-text character CRDT (`TextCrdt`) | ✅ | ✅ | ✅ |
-| **`TextCrdt` delta sync — `version_vector` / `delta_since` / `apply_delta` (`#lztextsync`)** | ✅ | ✅ | ✅ |
-| Move-aware sequence CRDT (`SeqCrdt`) | ✅ | ✅ | ✅ |
-| Registers (LWW / MV), `PnCounter`, `CellCrdt` | ✅ | ✅ | ✅ |
-| IPC wire — `Snapshot` + `Delta` + `CrdtSync` + shared-memory blobs | ✅ | ✅ | ~ |
-| State projection / mirror | ✅ | ✅ | ✅ |
-| FFI boundary | ✅ | ✅ | n/a |
-| Distributed plane (WebRTC transport + signaling) | ✅ | — | — |
-| Instrumentation / benchmarks | ✅ | — | — |
+The full `lazily` capability set across every binding. Legend: ✅ shipped ·
+`~` partial · `—` absent or not applicable. The canonical matrix with per-cell
+notes and platform carve-outs lives in
+[`lazily-spec` § Cross-Language Coverage](../lazily-spec/docs/coverage.md).
+
+<!-- coverage-table:start -->
+| Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
+| --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
+| Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |
+| Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Harel state charts | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Keyed cell collections (`CellMap` / `CellTree`) + reconcile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Memoized semantic tree (`SemTree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | — | — | — | — | — | — | — | — |
+| Free-text character CRDT (`TextCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `TextCrdt` delta sync (`version_vector` / `delta_since` / `apply_delta`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Move-aware sequence CRDT (`SeqCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Lossless tree — concurrent merge convergence | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Registers (LWW / MV) + `PnCounter` + `CellCrdt` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| IPC wire — `Snapshot` + `Delta` + `CrdtSync` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ~ | ~ | ✅ | ✅ | ✅ |
+| Distributed CRDT plane (`CrdtPlaneRuntime` / anti-entropy) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Distributed plane — WebRTC transport + signaling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Causal receipts (`CausalReceipts` outcome projection) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Instrumentation / benchmarks | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+<!-- coverage-table:end -->
 
 CRDT convergence and the wire protocol are pinned by the shared conformance fixtures
 and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
@@ -53,6 +75,7 @@ and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 |--------|------------|
 | `@lazily-hub/lazily-js` | `lazily-spec` IPC wire types: `Snapshot`, `Delta`, `DeltaOp`, `IpcMessage` (`Snapshot` / `Delta` / `CrdtSync`), `NodeState`, `IpcValue`, `PeerPermissions`, `SessionHandshake`, `BINDING_CAPABILITIES` |
 | `@lazily-hub/lazily-js/reactive` | Reactive dependency graph: `Context`, `Cell`, `Slot`, `Signal`, `Effect` |
+| `@lazily-hub/lazily-js/reactive-async` | Async reactive graph: `AsyncContext` — Promise-driven slots/effects with revision-guarded stale-completion discard, in-flight dedup, and cancellation |
 | `@lazily-hub/lazily-js/state-machine` | Flat finite-state-machine kernel backed by a reactive `Cell` |
 | `@lazily-hub/lazily-js/statechart` | Harel/SCXML chart interpreter plus `ChartBuilder`, `StateBuilder`, `TransitionBuilder` |
 | `@lazily-hub/lazily-js/collections` | `CellMap`, `CellTree`, keyed reconciliation, and LIS move minimization |
@@ -60,6 +83,8 @@ and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 | `@lazily-hub/lazily-js/seq-crdt` | Move-aware sequence CRDT using independent LWW value / position / deletion registers |
 | `@lazily-hub/lazily-js/text-crdt` | Fugue/RGA character CRDT |
 | `@lazily-hub/lazily-js/stable-id` | Manufactured text identity: anchors, content hashes, similarity alignment |
+| `@lazily-hub/lazily-js/signaling` | WebSocket signaling protocol: `ClientMessage` / `ServerMessage`, `SignalingClient`, `SignalingRoom` routing (anti-spoof, roster), `SignalingPermissions` |
+| `@lazily-hub/lazily-js/distributed` | Distributed plane: `DataChannel` seam + `InMemoryDataChannel`, `WebRtcSink` / `WebRtcSource`, `CrdtPlaneRuntime` anti-entropy, and the browser `RTCPeerConnection` adapter |
 | `@lazily-hub/lazily-js/state-projection` | koffi FFI consumer for agent-doc `DocumentStateProjection` |
 
 ## Reactive graph
@@ -96,6 +121,40 @@ ctx.setCell(a, 11);
 ctx.getSignal(parity); // "odd", already materialized
 ```
 
+## Async reactive context
+
+`AsyncContext` (from `@lazily-hub/lazily-js/reactive-async`) is a **separate**
+reactive surface for derivations whose values are produced by `async` functions.
+It is not an overload of the synchronous `Context`: futures introduce in-flight
+state, stale completion, cancellation, and dependency tracking across `await`
+that the synchronous graph does not have. Cells remain the synchronous input
+layer; computed slots, memos, and effects are async.
+
+Each async slot runs an `Empty → Computing → Resolved/Error` state machine with
+**revision-guarded publish** (a completion is published only if the slot's
+revision is still current, so a stale result is discarded), **in-flight
+deduplication** (concurrent `getAsync` callers share one compute), and
+cooperative cancellation. Async effects serialize reruns and always run the
+previous cleanup before the next body.
+
+```js
+import { AsyncContext } from "@lazily-hub/lazily-js/reactive-async";
+
+const ctx = new AsyncContext();
+const userId = ctx.cell(1);
+
+const profile = ctx.computedAsync(async (cctx) => {
+  const id = cctx.getCell(userId); // dependency registered before the await
+  return await fetchProfile(id);
+});
+
+await ctx.getAsync(profile); // spawns the compute, awaits the value
+ctx.get(profile); // synchronous cached read once resolved (undefined while pending)
+
+ctx.setCell(userId, 2); // supersedes any in-flight compute; slot re-resolves
+await ctx.getAsync(profile); // the profile for user 2
+```
+
 ## State machine and state charts
 
 `StateMachine` is the flat finite-state-machine kernel: a pure
@@ -280,17 +339,54 @@ snapshot.filterReadable(permissions, 11).nodes.length; // 0
 
 `BINDING_CAPABILITIES` advertises the JS binding truthfully: reactive core,
 IPC, CRDT, keyed collections, semantic tree, sequence/text CRDT, stable-id,
-state machine, state charts, permissions, and capability negotiation are
-shipped; C-ABI FFI is `none` because browser/Worker JS cannot host a native
-in-process ABI; async context, signaling, and WebRTC transports are not shipped
-by this package. The same payload types can still be carried by any transport a
-host application owns.
+state machine, state charts, permissions, capability negotiation, async context,
+signaling, and the WebRTC transport are shipped; C-ABI FFI is `none` because
+browser/Worker JS cannot host a native in-process ABI. The same payload types
+can still be carried by any transport a host application owns.
+
+## Distributed plane
+
+The `@lazily-hub/lazily-js/signaling` and `@lazily-hub/lazily-js/distributed`
+entry points ship the distributed plane. Signaling is the kebab-tagged discovery
+wire protocol (`ClientMessage` / `ServerMessage`), a transport-agnostic
+`SignalingRoom` that enforces the anti-spoof forwarded-`from` invariant, and a
+`SignalingClient` over a pluggable socket seam. The distributed module is the
+WebRTC DataChannel IPC transport (`WebRtcSink` / `WebRtcSource` with outbound
+permission filtering, over any `DataChannel`) plus `CrdtPlaneRuntime`, the CRDT
+anti-entropy runtime. Both are koffi-free and testable over an in-memory loopback
+with zero network; "real" WebRTC is reached through a browser platform adapter
+(`RtcPeerChannel` / `RtcPeerConnector`) that wraps the `RTCDataChannel` /
+`RTCPeerConnection` globals with no npm dependency.
+
+```js
+import { CrdtPlaneRuntime, InMemoryDataChannel, WebRtcSink, WebRtcSource } from "@lazily-hub/lazily-js/distributed";
+import { SignalingRoom, ClientMessage } from "@lazily-hub/lazily-js/signaling";
+import { IpcMessage, IpcValue, PeerPermissions, OpKind, Snapshot, NodeSnapshot } from "@lazily-hub/lazily-js";
+
+// Route a signaling handshake with server-stamped `from` (anti-spoof).
+const room = new SignalingRoom();
+room.receive("a", ClientMessage.join(1));
+room.receive("b", ClientMessage.join(2));
+room.receive("a", ClientMessage.offer(2, "SDP-A")); // -> { to: "b", message: offer{ from: 1, sdp: "SDP-A" } }
+
+// Two replicas converge over an anti-entropy exchange.
+const alice = new CrdtPlaneRuntime(1);
+const bob = new CrdtPlaneRuntime(2);
+alice.register(1, "doc/title");
+bob.register(1, "doc/title");
+const op = alice.localUpdate(1, Date.now() * 1000, IpcValue.inline([66]));
+bob.ingest(alice.syncFrame(), Date.now() * 1000); // 1 op applied; re-ingest applies 0
+```
 
 ## Conformance
 
 lazily-js replays the shared `lazily-spec` fixtures for IPC, agent-doc state,
 keyed collections (`CellMap`, `CellTree`, LIS reconciliation), semantic tree,
-sequence and text CRDTs, manufactured text identity, and Harel state charts.
+sequence and text CRDTs (incl. `TextCrdt` delta sync, `#lztextsync`:
+`textcrdt_convergence.json` + `textcrdt_delta_sync.json`), manufactured text
+identity, Harel state charts, the signaling protocol (`signaling/frames.json`,
+`signaling/anti_spoof_session.json`), and the distributed CRDT plane
+(`distributed/crdt_sync_frames.json`, `distributed/anti_entropy_converge.json`).
 It also validates generated wire values against the canonical JSON Schemas.
 
 `npm test` builds the [`lazily-formal`][formal] Lean 4 model when that sibling
@@ -309,9 +405,15 @@ names the Lean theorems it mirrors:
 | `Collection` | `collection-properties.test.js` | `setEntryValue_preserves_{membership,order,siblings}`, `moveKey_preserves_{membership,values}`, `moveKey_advances_order`, `addKey_advances_membership_and_order`, `Family.get_idempotent_after_first` |
 | `Tree` | `tree-properties.test.js` | `setNodeValue_preserves_{other_nodes,node_signals}`, `moveChild_preserves_{non_parent,parent_value}`, `moveChild_advances_order_signal_only` |
 | `Reconciliation` | `reconciliation-properties.test.js` | `lisBy_longest`, `reconcile_move_minimized`, `reconcile_stable_not_invalidated` |
+| `AsyncSlotState` | `reactive-async.test.js` | `stale_completeOk_discarded`, `current_completeOk_publishes`, `current_completeErr_to_error` |
+| `AsyncEffect` | `reactive-async.test.js` | `fire_blocked_during_cleanup`, `invalidate_from_idle_schedules`, `cleanupDone_resumes_deferred`, `dispose_absorbing`, `disposed_terminal` |
 
-`AsyncSlotState`, `AsyncEffect`, and thread-safe context theorems are not mirrored
-because lazily-js does not ship async or thread-safe context surfaces.
+Thread-safe context theorems are not mirrored because JavaScript is
+single-threaded (one event loop): a lock-backed context has no meaning on this
+runtime — the concurrency-layer platform carve-out. The `Signaling` /
+`SignalingRoster` formal models are exercised through the `SignalingRoom`
+fixture replay (`signaling/anti_spoof_session.json`) rather than a named-theorem
+property test.
 
 ## The lazily family
 
@@ -319,7 +421,7 @@ because lazily-js does not ship async or thread-safe context surfaces.
 |---------|----------|----------------|
 | [`lazily-rs`][rs] | Rust | `lazily` on crates.io; single-threaded, thread-safe, and async context layers |
 | [`lazily-py`][py] | Python | `lazily` on PyPI; dict-backed context plus IPC/shared-blob host types |
-| **`lazily-js`** | JavaScript / TypeScript | `@lazily-hub/lazily-js`; reactive core, spec wire types, state charts, CRDTs |
+| **`lazily-js`** | JavaScript / TypeScript | `@lazily-hub/lazily-js`; reactive core + async context, spec wire types, state charts, CRDTs, distributed plane (signaling + WebRTC) |
 | [`lazily-zig`][zig] | Zig | Zig library / FFI-oriented embedding surface |
 | [`lazily-kt`][kt] | Kotlin/JVM | Kotlin reactive core plus typed state charts |
 | [`lazily-dart`][dart] | Dart | Dart binding with statechart conformance |

package/bench/context.bench.mjs

@@ -0,0 +1,179 @@
+// Reactive-graph benchmarks for lazily-js — parity port of lazily-rs
+// `benches/context.rs` (the single-threaded `Context` variants).
+//
+// JS runs on a single event-loop thread, so the lazily-rs `ThreadSafeContext`
+// multi-worker contention benchmarks (thread_safe_contention,
+// thread_safe_effect_contention, thread_safe_graph_propagation) have no
+// like-for-like single-process counterpart here and are intentionally omitted.
+// Every group/case below is a 1:1 port of the matching `context`-variant in
+// lazily-rs, using the same widths/depths so numbers are cross-language
+// comparable. Constants mirror `benches/context.rs` exactly.
+
+import { bench, blackBox, run } from "./harness.mjs";
+import { Context } from "../src/reactive.js";
+
+const FAN_OUT_WIDTHS = [32, 256];
+const MEMO_CHAIN_DEPTH = 32;
+const BATCH_STORM_CELLS = 64;
+const SET_CELL_INVALIDATION_FAN_OUT = 512;
+
+// --- setup helpers (ports of setup_context_* in benches/context.rs) ---------
+
+function setupFanOut(width) {
+  const ctx = new Context();
+  const root = ctx.cell(0);
+  const slots = [];
+  for (let offset = 0; offset < width; offset++) {
+    slots.push(ctx.computed(() => (ctx.getCell(root) + offset) >>> 0));
+  }
+  for (const slot of slots) blackBox(ctx.get(slot));
+  return { ctx, root, slots };
+}
+
+function setupMemoChain(depth) {
+  const ctx = new Context();
+  const root = ctx.cell(0);
+  let tail = ctx.memo(() => ctx.getCell(root) % 2);
+  for (let i = 0; i < depth; i++) {
+    const previous = tail;
+    tail = ctx.computed(() => (ctx.get(previous) + 1) >>> 0);
+  }
+  blackBox(ctx.get(tail));
+  return { ctx, root, tail };
+}
+
+function setupBatchStorm(cellsLen) {
+  const ctx = new Context();
+  const cells = [];
+  for (let idx = 0; idx < cellsLen; idx++) cells.push(ctx.cell(idx));
+  let sink = 0;
+  const effectCells = cells.slice();
+  ctx.effect(() => {
+    let total = 0;
+    for (const cell of effectCells) total = (total + ctx.getCell(cell)) >>> 0;
+    sink = total;
+  });
+  return { ctx, cells, getSink: () => sink };
+}
+
+// --- cached_reads: steady-state cached slot read ----------------------------
+// Parity: bench_cached_reads "context" in lazily-rs/context.rs.
+// Setup runs once before registration; only the cached `get` is timed.
+{
+  const ctx = new Context();
+  const root = ctx.cell(21);
+  const doubled = ctx.computed(() => ctx.getCell(root) * 2);
+  blackBox(ctx.get(doubled)); // prime the cache
+  bench("cached_reads", "context", () => blackBox(ctx.get(blackBox(doubled))));
+}
+
+// --- cold_first_get: first (uncached) read of a freshly built slot ---------
+// Parity: bench_cold_first_get "context" (iter_batched — fresh ctx each call).
+bench.batched(
+  "cold_first_get",
+  "context",
+  () => {
+    const ctx = new Context();
+    const root = ctx.cell(21);
+    const doubled = ctx.computed(() => ctx.getCell(root) * 2);
+    return { ctx, doubled };
+  },
+  ({ ctx, doubled }) => blackBox(ctx.get(blackBox(doubled))),
+);
+
+// --- dependency_fan_out: one root cell invalidates N dependents ------------
+// Parity: bench_dependency_fan_out "context / {32,256}" (iter_batched).
+for (const width of FAN_OUT_WIDTHS) {
+  bench.batched(
+    "dependency_fan_out",
+    `context / ${width}`,
+    () => setupFanOut(width),
+    ({ ctx, root, slots }) => {
+      ctx.setCell(root, blackBox(1));
+      let total = 0;
+      for (const slot of slots) total = (total + ctx.get(slot)) >>> 0;
+      blackBox(total);
+    },
+  );
+}
+
+// --- set_cell_invalidation: cost of invalidating a wide fan-out ------------
+// Parity: bench_set_cell_invalidation "high_fan_out / 512" (iter_batched).
+// Only the setCell invalidation is timed (not the downstream recompute) —
+// matches the lazily-rs routine which times `set_cell` + `black_box(slots.len())`.
+bench.batched(
+  "set_cell_invalidation",
+  "high_fan_out / 512",
+  () => setupFanOut(SET_CELL_INVALIDATION_FAN_OUT),
+  ({ ctx, root, slots }) => {
+    ctx.setCell(root, blackBox(1));
+    blackBox(slots.length);
+  },
+);
+
+// --- memo_equality_suppression: memo chain that stays equal downstream -----
+// Parity: bench_memo_equality_suppression "context" (iter_batched).
+// root%2 memo head; setting root to an even value keeps the head's value equal
+// (0) so downstream caches survive — the memo guard path.
+bench.batched(
+  "memo_equality_suppression",
+  "context",
+  () => setupMemoChain(MEMO_CHAIN_DEPTH),
+  ({ ctx, root, tail }) => {
+    ctx.setCell(root, blackBox(2));
+    blackBox(ctx.get(blackBox(tail)));
+  },
+);
+
+// --- effect_flushing: effect re-runs on every cell change ------------------
+// Parity: bench_effect_flushing "context" (idempotent: advances next each call
+// so each setCell is a real 1->2->3 ... change, not a ==-guarded no-op).
+{
+  const ctx = new Context();
+  const root = ctx.cell(0);
+  let seen = 0;
+  ctx.effect(() => {
+    seen = (seen + ctx.getCell(root)) >>> 0;
+  });
+  let next = 0;
+  bench("effect_flushing", "context", () => {
+    next = (next + 1) >>> 0;
+    ctx.setCell(root, blackBox(next));
+    blackBox(seen);
+  });
+}
+
+// --- batch_storms: coalesced batched writes to many cells -----------------
+// Parity: bench_batch_storms "context / 64".
+{
+  const { ctx, cells, getSink } = setupBatchStorm(BATCH_STORM_CELLS);
+  let base = BATCH_STORM_CELLS;
+  bench("batch_storms", `context / ${BATCH_STORM_CELLS}`, () => {
+    base = (base + BATCH_STORM_CELLS) >>> 0;
+    ctx.batch(() => {
+      for (let i = 0; i < cells.length; i++) {
+        ctx.setCell(cells[i], blackBox((base + i) >>> 0));
+      }
+    });
+    blackBox(getSink());
+  });
+}
+
+// --- typed_cache_reads: direct slot/cell reads ----------------------------
+// Parity: bench_typed_cache_reads "context_slot" / "context_cell".
+{
+  const ctx = new Context();
+  const cell = ctx.cell(42);
+  const slot = ctx.computed(() => ctx.getCell(cell));
+  blackBox(ctx.get(slot)); // prime
+  bench("typed_cache_reads", "context_slot", () => blackBox(ctx.get(blackBox(slot))));
+}
+{
+  const ctx = new Context();
+  const cell = ctx.cell(99);
+  bench("typed_cache_reads", "context_cell", () => blackBox(ctx.getCell(blackBox(cell))));
+}
+
+await run({
+  format: process.env.BENCH_FORMAT === "json" ? "json" : "markdown",
+});