@lazily-hub/lazily-js 0.18.0 → 0.19.0

package/README.md

@@ -38,7 +38,7 @@ notes and platform carve-outs lives in
 <!-- coverage-table:start -->
 | Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
-| Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive graph — core `Cell` / `Slot` / `Effect` (+ derived `Signal` = `Slot.eager`) / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Keyed-map materialization (`SlotMap`) — mint-on-access derived slots: transparency + deferral (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Thread-safe keyed map (`ThreadSafeSlotMap`) — `Send + Sync` + materialization confluence (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Async keyed map (`AsyncSlotMap`) — eventual transparency (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -78,6 +78,14 @@ notes and platform carve-outs lives in
 | Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Instrumentation / benchmarks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Temporal sources — `TimerCell` / `IntervalCell` / `CronCell` / `DeadlineCell` over a logical clock (`#lztime`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Rate-shaping operators — `DebounceCell` / `ThrottleCell` / `SampleCell` / `ProbabilisticSampleCell` (`#lzrateshape`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Membership + failure detection — `MembershipCell` (SWIM + Phi-accrual) / `PeerSet` / `PeerChangeEvent` (`#lzmemb`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Distributed coordination — `LeaseCell` / `LeaderCell` / `LockCell` / `SemaphoreCell` / `BarrierCell`+`QuorumCell` (`#lzcoord`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Presence + ephemeral plane — `PresenceCell` / `AwarenessCell` / `EphemeralCell` + `Ephemeral`/`Durable` markers (`#lzpresence`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Stream windowing — `TumblingWindow` / `SlidingWindow` / `SessionWindow` over the merge algebra (`#lzwindow`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Fault tolerance — `CircuitBreakerCell` / `RetryPolicyCell` / `BulkheadCell` / `TimeoutCell` (`#lzresilience`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Embedded-service plane — `HealthCell` / `ReadinessCell` / `DiscoveryCell` / `ServiceRegistry` (`#lzservice`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 <!-- coverage-table:end -->
 
 Two JS ✅ marks are backed by runtime-specific mechanisms while keeping the core isomorphic:
@@ -119,10 +127,12 @@ JavaScript. The family is:
 
 - **Slot** - lazy, memoized derived value;
 - **Cell** - mutable source value;
-- **Signal** - eager derived value that re-materializes as soon as a dependency
-  invalidates;
 - **Effect** - side-effecting observer with cleanup.
 
+The core primitives are **Cell** / **Slot** / **Effect**. **`Signal` is a
+derived construct, not a core primitive** — `Signal ≡ Slot.eager`, a memo Slot
+plus a puller Effect that re-materializes as soon as a dependency invalidates.
+
 Dependencies are discovered dynamically while a slot/effect/signal computes.
 Invalidation is pull-based and glitch-free; `memo`/`Signal` use equality guards
 to suppress downstream work when a recompute produces the same value. `batch`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), sync/async/thread-safe keyed reactive maps (ReactiveMap/CellMap/SlotMap), the lazily-spec IPC wire types + C-ABI FFI boundary (isomorphic channel + Node native binding), keyed cell collections + LIS reconciliation, the memoized semantic tree, the move-aware sequence CRDT, the Fugue/RGA text CRDT, manufactured text identity, full-Harel state charts, an FFI state-projection consumer, and an in-library instrumentation/benchmark API.",
   "license": "MIT",
   "repository": {
@@ -77,6 +77,38 @@
       "types": "./src/relay.d.ts",
       "default": "./src/relay.js"
     },
+    "./temporal": {
+      "types": "./src/temporal.d.ts",
+      "default": "./src/temporal.js"
+    },
+    "./rateshape": {
+      "types": "./src/rateshape.d.ts",
+      "default": "./src/rateshape.js"
+    },
+    "./membership": {
+      "types": "./src/membership.d.ts",
+      "default": "./src/membership.js"
+    },
+    "./coordination": {
+      "types": "./src/coordination.d.ts",
+      "default": "./src/coordination.js"
+    },
+    "./presence": {
+      "types": "./src/presence.d.ts",
+      "default": "./src/presence.js"
+    },
+    "./windowing": {
+      "types": "./src/windowing.d.ts",
+      "default": "./src/windowing.js"
+    },
+    "./resilience": {
+      "types": "./src/resilience.d.ts",
+      "default": "./src/resilience.js"
+    },
+    "./service": {
+      "types": "./src/service.d.ts",
+      "default": "./src/service.js"
+    },
     "./sem-tree": {
       "types": "./src/sem-tree.d.ts",
       "default": "./src/sem-tree.js"
@@ -116,7 +148,7 @@
     }
   },
   "scripts": {
-    "build": "node --check src/index.js && node --check src/transport.js && node --check src/shm-backend.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/reactive-family.js && node --check src/async-reactive-family.js && node --check src/thread-safe.js && node --check src/thread-safe-reactive-family.js && node --check src/ffi.js && node --check src/ffi-node.js && node --check src/instrumentation.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/queue.js && node --check src/merge.js && node --check src/relay.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/indexeddb-outbox.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/graph-view.js && node --check src/signaling.js && node --check src/distributed.js",
+    "build": "node --check src/index.js && node --check src/transport.js && node --check src/shm-backend.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/reactive-family.js && node --check src/async-reactive-family.js && node --check src/thread-safe.js && node --check src/thread-safe-reactive-family.js && node --check src/ffi.js && node --check src/ffi-node.js && node --check src/instrumentation.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/queue.js && node --check src/merge.js && node --check src/relay.js && node --check src/rateshape.js && node --check src/membership.js && node --check src/coordination.js && node --check src/presence.js && node --check src/windowing.js && node --check src/resilience.js && node --check src/service.js && node --check src/temporal.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/indexeddb-outbox.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/graph-view.js && node --check src/signaling.js && node --check src/distributed.js",
     "test:formal": "node scripts/formal-check.mjs",
     "bench": "node bench/context.bench.mjs",
     "bench:scale": "node --max-old-space-size=8192 bench/scale.bench.mjs",

package/src/coordination.d.ts

@@ -0,0 +1,81 @@
+// Distributed coordination (#lzcoord) — the JS port.
+// See coordination.js and `lazily-spec/docs/coordination.md`.
+
+import type { Context, CellHandle } from "./reactive.js";
+
+export class LeaseCore<P = unknown> {
+  fence: number;
+  isHeld(now: number): boolean;
+  holder(now: number): P | null;
+  acquire(peer: P, now: number, ttl: number): number | null;
+  renew(peer: P, now: number, ttl: number): boolean;
+  release(peer: P): void;
+  tick(now: number): boolean;
+}
+
+export class LeaseCell<P = unknown> {
+  constructor(ctx: Context);
+  readonly holderCell: CellHandle<P | null>;
+  acquire(peer: P, now: number, ttl: number): number | null;
+  renew(peer: P, now: number, ttl: number): boolean;
+  release(peer: P, now: number): void;
+  tick(now: number): boolean;
+  holder(now: number): P | null;
+  isHeld(now: number): boolean;
+  fence(): number;
+}
+
+export type LeaderRoleLabel = "Leader" | "Follower" | "Candidate";
+export const LeaderRole: Readonly<{ Leader: "Leader"; Follower: "Follower"; Candidate: "Candidate" }>;
+
+export class LeaderCell<P = unknown> {
+  constructor(ctx: Context, me: P);
+  readonly currentLeaderCell: CellHandle<P | null>;
+  campaign(now: number, ttl: number): LeaderRoleLabel;
+  contend(peer: P, now: number, ttl: number): LeaderRoleLabel;
+  tick(now: number): LeaderRoleLabel;
+  currentLeader(now: number): P | null;
+  role(now: number): LeaderRoleLabel;
+}
+
+export class LockCell<P = unknown> {
+  constructor(ctx: Context);
+  readonly isLockedCell: CellHandle<boolean>;
+  acquire(peer: P, now: number, ttl: number): number | null;
+  release(peer: P, now: number): void;
+  tick(now: number): boolean;
+  validate(fence: number): boolean;
+  isLocked(now: number): boolean;
+  fence(): number;
+}
+
+export class SemaphoreCore {
+  constructor(capacity: number);
+  available(): number;
+  acquire(): boolean;
+  release(): void;
+}
+
+export class SemaphoreCell {
+  constructor(ctx: Context, capacity: number);
+  readonly permitsAvailableCell: CellHandle<number>;
+  acquire(): boolean;
+  release(): void;
+  permitsAvailable(): number;
+}
+
+export class BarrierCore<P = unknown> {
+  constructor(required: number);
+  arrive(peer: P): boolean;
+  count(): number;
+  isOpen(): boolean;
+}
+
+export class BarrierCell<P = unknown> {
+  constructor(ctx: Context, required: number);
+  static quorum<P = unknown>(ctx: Context, total: number): BarrierCell<P>;
+  readonly isOpenCell: CellHandle<boolean>;
+  arrive(peer: P): boolean;
+  count(): number;
+  isOpen(): boolean;
+}

package/src/coordination.js

@@ -0,0 +1,283 @@
+// Distributed coordination (#lzcoord) — the JS port.
+//
+// See `lazily-spec/docs/coordination.md` and the formal model
+// `lazily-formal/LazilyFormal/Coordination.lean`. Lease / leader / lock /
+// semaphore / barrier + quorum primitives, each a pure compute core split from a
+// reactive cell projecting the salient reader. Time is the logical clock. A
+// holder of `null` means "no holder".
+
+// ---------------------------------------------------------------------------
+// Lease + fencing token
+// ---------------------------------------------------------------------------
+
+/** Single-writer lease authority with a monotone fencing token. */
+export class LeaseCore {
+  constructor() {
+    this.holderPeer = null;
+    this.expiry = 0;
+    this.fence = 0;
+  }
+  #isExpired(now) {
+    return this.holderPeer !== null && now >= this.expiry;
+  }
+  isHeld(now) {
+    return this.holderPeer !== null && !this.#isExpired(now);
+  }
+  holder(now) {
+    return this.isHeld(now) ? this.holderPeer : null;
+  }
+  acquire(peer, now, ttl) {
+    if (this.holderPeer === null || this.#isExpired(now)) {
+      this.fence += 1;
+      this.holderPeer = peer;
+      this.expiry = now + ttl;
+      return this.fence;
+    }
+    if (this.holderPeer === peer) {
+      this.expiry = now + ttl; // renew keeps fence
+      return this.fence;
+    }
+    return null;
+  }
+  renew(peer, now, ttl) {
+    if (this.isHeld(now) && this.holderPeer === peer) {
+      this.expiry = now + ttl;
+      return true;
+    }
+    return false;
+  }
+  release(peer) {
+    if (this.holderPeer === peer) this.holderPeer = null;
+  }
+  tick(now) {
+    if (this.#isExpired(now)) {
+      this.holderPeer = null;
+      return true;
+    }
+    return false;
+  }
+}
+
+/** Reactive lease: projects the holder onto a cell. */
+export class LeaseCell {
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.core = new LeaseCore();
+    this.holderCell = ctx.cell(null);
+  }
+  #refresh(now) {
+    this.ctx.setCell(this.holderCell, this.core.holder(now));
+  }
+  acquire(peer, now, ttl) {
+    const r = this.core.acquire(peer, now, ttl);
+    this.#refresh(now);
+    return r;
+  }
+  renew(peer, now, ttl) {
+    const r = this.core.renew(peer, now, ttl);
+    this.#refresh(now);
+    return r;
+  }
+  release(peer, now) {
+    this.core.release(peer);
+    this.#refresh(now);
+  }
+  tick(now) {
+    const r = this.core.tick(now);
+    this.#refresh(now);
+    return r;
+  }
+  holder(now) {
+    return this.core.holder(now);
+  }
+  isHeld(now) {
+    return this.core.isHeld(now);
+  }
+  fence() {
+    return this.core.fence;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Leader / follower / candidate
+// ---------------------------------------------------------------------------
+
+export const LeaderRole = Object.freeze({
+  Leader: "Leader",
+  Follower: "Follower",
+  Candidate: "Candidate",
+});
+
+/** Reactive leadership over a lease from node `me`'s perspective. */
+export class LeaderCell {
+  constructor(ctx, me) {
+    this.ctx = ctx;
+    this.me = me;
+    this.core = new LeaseCore();
+    this.currentLeaderCell = ctx.cell(null);
+  }
+  #refresh(now) {
+    this.ctx.setCell(this.currentLeaderCell, this.core.holder(now));
+  }
+  campaign(now, ttl) {
+    this.core.acquire(this.me, now, ttl);
+    this.#refresh(now);
+    return this.role(now);
+  }
+  contend(peer, now, ttl) {
+    this.core.acquire(peer, now, ttl);
+    this.#refresh(now);
+    return this.role(now);
+  }
+  tick(now) {
+    this.core.tick(now);
+    this.#refresh(now);
+    return this.role(now);
+  }
+  currentLeader(now) {
+    return this.core.holder(now);
+  }
+  role(now) {
+    const h = this.core.holder(now);
+    if (h === null) return LeaderRole.Candidate;
+    return h === this.me ? LeaderRole.Leader : LeaderRole.Follower;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Distributed lock + fencing
+// ---------------------------------------------------------------------------
+
+/** Reactive distributed mutex over a lease + fencing token. */
+export class LockCell {
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.core = new LeaseCore();
+    this.isLockedCell = ctx.cell(false);
+  }
+  #refresh(now) {
+    this.ctx.setCell(this.isLockedCell, this.core.isHeld(now));
+  }
+  acquire(peer, now, ttl) {
+    const r = this.core.acquire(peer, now, ttl);
+    this.#refresh(now);
+    return r;
+  }
+  release(peer, now) {
+    this.core.release(peer);
+    this.#refresh(now);
+  }
+  tick(now) {
+    const r = this.core.tick(now);
+    this.#refresh(now);
+    return r;
+  }
+  /** Whether `fence` is the current (non-stale) fencing token. */
+  validate(fence) {
+    return this.core.fence === fence;
+  }
+  isLocked(now) {
+    return this.core.isHeld(now);
+  }
+  fence() {
+    return this.core.fence;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Semaphore
+// ---------------------------------------------------------------------------
+
+/** Bounded permit pool compute core. */
+export class SemaphoreCore {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.acquired = 0;
+  }
+  available() {
+    return this.capacity - this.acquired;
+  }
+  acquire() {
+    if (this.acquired < this.capacity) {
+      this.acquired += 1;
+      return true;
+    }
+    return false;
+  }
+  release() {
+    if (this.acquired > 0) this.acquired -= 1;
+  }
+}
+
+/** Reactive semaphore: projects permitsAvailable onto a cell. */
+export class SemaphoreCell {
+  constructor(ctx, capacity) {
+    this.ctx = ctx;
+    this.core = new SemaphoreCore(capacity);
+    this.permitsAvailableCell = ctx.cell(capacity);
+  }
+  #refresh() {
+    this.ctx.setCell(this.permitsAvailableCell, this.core.available());
+  }
+  acquire() {
+    const r = this.core.acquire();
+    this.#refresh();
+    return r;
+  }
+  release() {
+    this.core.release();
+    this.#refresh();
+  }
+  permitsAvailable() {
+    return this.ctx.getCell(this.permitsAvailableCell);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Barrier / quorum
+// ---------------------------------------------------------------------------
+
+/** Wait-for-N gate over distinct arriving peers. */
+export class BarrierCore {
+  constructor(required) {
+    this.required = required;
+    this.arrived = new Set();
+  }
+  arrive(peer) {
+    this.arrived.add(peer);
+    return this.isOpen();
+  }
+  count() {
+    return this.arrived.size;
+  }
+  isOpen() {
+    return this.count() >= this.required;
+  }
+}
+
+/** Reactive wait-for-N gate. A quorum is a barrier with required = total/2 + 1. */
+export class BarrierCell {
+  constructor(ctx, required) {
+    this.ctx = ctx;
+    this.core = new BarrierCore(required);
+    this.isOpenCell = ctx.cell(this.core.isOpen());
+  }
+  /** A quorum gate: opens at strict majority of `total`. */
+  static quorum(ctx, total) {
+    return new BarrierCell(ctx, Math.floor(total / 2) + 1);
+  }
+  #refresh() {
+    this.ctx.setCell(this.isOpenCell, this.core.isOpen());
+  }
+  arrive(peer) {
+    const r = this.core.arrive(peer);
+    this.#refresh();
+    return r;
+  }
+  count() {
+    return this.core.count();
+  }
+  isOpen() {
+    return this.ctx.getCell(this.isOpenCell);
+  }
+}

package/src/membership.d.ts

@@ -0,0 +1,52 @@
+// Membership + failure detection (#lzmemb) — the JS port.
+// See membership.js and `lazily-spec/docs/membership.md`.
+
+import type { Context, CellHandle } from "./reactive.js";
+
+export type PeerStateLabel = "Alive" | "Suspect" | "Dead" | "Left";
+export const PeerState: Readonly<{
+  Alive: "Alive";
+  Suspect: "Suspect";
+  Dead: "Dead";
+  Left: "Left";
+}>;
+
+export interface MembershipConfig {
+  phiThreshold: number;
+  suspectTimeout: number;
+  maxSamples: number;
+  minStd: number;
+}
+export const defaultMembershipConfig: Readonly<MembershipConfig>;
+
+export type PeerChangeEvent<P> =
+  | { type: "Joined"; peer: P }
+  | { type: "Left"; peer: P }
+  | { type: "StateChanged"; peer: P; from: PeerStateLabel; to: PeerStateLabel };
+
+export class PhiAccrual {
+  constructor(maxSamples: number, minStd: number);
+  heartbeat(now: number): void;
+  phi(now: number): number;
+}
+
+export class MembershipCore<P = unknown> {
+  constructor(config?: Partial<MembershipConfig>);
+  aliveSet(): P[];
+  state(peer: P): PeerStateLabel | null;
+  join(peer: P, now: number): PeerChangeEvent<P>[];
+  heartbeat(peer: P, now: number): PeerChangeEvent<P>[];
+  leave(peer: P, now: number): PeerChangeEvent<P>[];
+  tick(now: number): PeerChangeEvent<P>[];
+}
+
+export class MembershipCell<P = unknown> {
+  constructor(ctx: Context, config?: Partial<MembershipConfig>);
+  readonly peerSetCell: CellHandle<P[]>;
+  join(peer: P, now: number): PeerChangeEvent<P>[];
+  heartbeat(peer: P, now: number): PeerChangeEvent<P>[];
+  leave(peer: P, now: number): PeerChangeEvent<P>[];
+  tick(now: number): PeerChangeEvent<P>[];
+  peerSet(): P[];
+  state(peer: P): PeerStateLabel | null;
+}

package/src/membership.js

@@ -0,0 +1,178 @@
+// Membership + failure detection (#lzmemb) — the JS port.
+//
+// See `lazily-spec/docs/membership.md` and the formal model
+// `lazily-formal/LazilyFormal/Membership.lean`. A MembershipCell is a reactive
+// view of the live peer set backed by SWIM-style heartbeats + a Phi-accrual
+// failure detector; the derived peerSet is the Alive peers. The pure core
+// (MembershipCore + PhiAccrual) is the phi math + SWIM state machine, split from
+// the reactive cell projecting the alive set onto a Context cell.
+
+/** Per-peer liveness state (SWIM). */
+export const PeerState = Object.freeze({
+  Alive: "Alive",
+  Suspect: "Suspect",
+  Dead: "Dead",
+  Left: "Left",
+});
+
+/** Default detector + state-machine tunables. */
+export const defaultMembershipConfig = Object.freeze({
+  phiThreshold: 8.0,
+  suspectTimeout: 5,
+  maxSamples: 100,
+  minStd: 0.1,
+});
+
+/** Phi-accrual failure detector; `phi` uses the bit-portable Akka logistic
+ *  approximation of the normal CDF so every binding agrees. */
+export class PhiAccrual {
+  constructor(maxSamples, minStd) {
+    this.maxSamples = Math.max(1, maxSamples);
+    this.minStd = minStd;
+    this.window = [];
+    this.lastHeartbeat = null;
+  }
+  heartbeat(now) {
+    if (this.lastHeartbeat !== null) {
+      this.window.push(now - this.lastHeartbeat);
+      while (this.window.length > this.maxSamples) this.window.shift();
+    }
+    this.lastHeartbeat = now;
+  }
+  #mean() {
+    return this.window.reduce((a, b) => a + b, 0) / this.window.length;
+  }
+  #std(mean) {
+    const v = this.window.reduce((a, x) => a + (x - mean) * (x - mean), 0) / this.window.length;
+    return Math.max(Math.sqrt(v), this.minStd);
+  }
+  phi(now) {
+    if (this.lastHeartbeat === null || this.window.length === 0) return 0.0;
+    const elapsed = now - this.lastHeartbeat;
+    const mean = this.#mean();
+    const std = this.#std(mean);
+    const y = (elapsed - mean) / std;
+    const e = Math.exp(-y * (1.5976 + 0.070566 * y * y));
+    return elapsed > mean ? -Math.log10(e / (1 + e)) : -Math.log10(1 - 1 / (1 + e));
+  }
+}
+
+/** The pure membership compute core: the SWIM state machine over a keyed peer
+ *  map, driven by heartbeats and a logical clock. Emits PeerChangeEvents:
+ *  `{ type: "Joined"|"Left"|"StateChanged", peer, from?, to? }`. */
+export class MembershipCore {
+  constructor(config = defaultMembershipConfig) {
+    this.config = { ...defaultMembershipConfig, ...config };
+    this.peers = new Map(); // peer -> { state, detector, suspectSince }
+  }
+  #newDetector() {
+    return new PhiAccrual(this.config.maxSamples, this.config.minStd);
+  }
+  /** The alive peer set, sorted ascending (matches the spec's BTreeSet). */
+  aliveSet() {
+    return [...this.peers.entries()]
+      .filter(([, r]) => r.state === PeerState.Alive)
+      .map(([p]) => p)
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+  state(peer) {
+    return this.peers.get(peer)?.state ?? null;
+  }
+  join(peer, now) {
+    const detector = this.#newDetector();
+    detector.heartbeat(now);
+    const prev = this.peers.get(peer)?.state ?? null;
+    this.peers.set(peer, { state: PeerState.Alive, detector, suspectSince: null });
+    if (prev === null) return [{ type: "Joined", peer }];
+    if (prev === PeerState.Alive) return [];
+    return [{ type: "StateChanged", peer, from: prev, to: PeerState.Alive }];
+  }
+  heartbeat(peer, now) {
+    const record = this.peers.get(peer);
+    if (record === undefined) return this.join(peer, now);
+    record.detector.heartbeat(now);
+    const from = record.state;
+    if (from !== PeerState.Alive && from !== PeerState.Left) {
+      record.state = PeerState.Alive;
+      record.suspectSince = null;
+      return [{ type: "StateChanged", peer, from, to: PeerState.Alive }];
+    }
+    return [];
+  }
+  leave(peer, _now) {
+    const record = this.peers.get(peer);
+    if (record === undefined || record.state === PeerState.Left) return [];
+    record.state = PeerState.Left;
+    record.suspectSince = null;
+    return [{ type: "Left", peer }];
+  }
+  tick(now) {
+    const events = [];
+    for (const [peer, record] of this.peers) {
+      if (record.state === PeerState.Alive) {
+        if (record.detector.phi(now) > this.config.phiThreshold) {
+          record.state = PeerState.Suspect;
+          record.suspectSince = now;
+          events.push({ type: "StateChanged", peer, from: PeerState.Alive, to: PeerState.Suspect });
+        }
+      } else if (record.state === PeerState.Suspect) {
+        if (record.suspectSince !== null && now - record.suspectSince >= this.config.suspectTimeout) {
+          record.state = PeerState.Dead;
+          events.push({ type: "StateChanged", peer, from: PeerState.Suspect, to: PeerState.Dead });
+        }
+      }
+    }
+    return events;
+  }
+}
+
+/** Compare two alive-set arrays for equality (used by the reactive cell). */
+function setEquals(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** Reactive membership: drives a MembershipCore and projects the alive set onto
+ *  a Context cell so peerSet invalidates only on a set change. */
+export class MembershipCell {
+  constructor(ctx, config = defaultMembershipConfig) {
+    this.ctx = ctx;
+    this.core = new MembershipCore(config);
+    this.peerSetCell = ctx.cell([]);
+  }
+  #refresh() {
+    const next = this.core.aliveSet();
+    // Only write when the set changed, so the reader's PartialEq guard holds even
+    // though the array identity differs each call.
+    if (!setEquals(this.ctx.getCell(this.peerSetCell), next)) {
+      this.ctx.setCell(this.peerSetCell, next);
+    }
+  }
+  join(peer, now) {
+    const ev = this.core.join(peer, now);
+    this.#refresh();
+    return ev;
+  }
+  heartbeat(peer, now) {
+    const ev = this.core.heartbeat(peer, now);
+    this.#refresh();
+    return ev;
+  }
+  leave(peer, now) {
+    const ev = this.core.leave(peer, now);
+    this.#refresh();
+    return ev;
+  }
+  tick(now) {
+    const ev = this.core.tick(now);
+    this.#refresh();
+    return ev;
+  }
+  peerSet() {
+    return this.ctx.getCell(this.peerSetCell);
+  }
+  state(peer) {
+    return this.core.state(peer);
+  }
+}