fix(pulse-core): reference-count shared subscriptions

[determined-001]

Stacked on #999. Merge #997 → #998 → #999 → this.

The bug

subscribe() and subscribeContract() memoise by key, so concurrent callers asking for the same address or contract receive the same Watcher object. unsubscribe() called stop() on it unconditionally.

Watcher.stop() sets _stopped, calls removeAllListeners(), and makes emit() return false without dispatching — so the first caller to leave silently killed every other caller's event flow.

Proven against pulse-core:

✓ expect(wA).toBe(wB)                               // both callers share ONE Watcher
✓ wB live before A disconnects                      // bGot.length === 1
✓ engine.unsubscribe(ADDR) → wB.stopped === true    // A's teardown stops B's watcher
✓ wB.emit(...) === false, bGot.length still 1       // B silently dead

Why it was invisible

In apps/web both SSE routes key on data that is not per-connection — address, and `contract:${contractId}` — and unsubscribe on teardown. So when one visitor closed their tab, every other visitor watching the same contract kept an open connection, kept receiving heartbeats, and never received another event. Indistinguishable from a quiet contract.

Cheap to weaponise: connect to a popular contract, disconnect, repeat, and every other viewer's stream goes silent.

The fix

A namespaced refcount map (addr: / contract: / config:, since the three registries have independent key spaces). subscribe*() retains, unsubscribe*() releases, and the watcher stops only on the last release.

Details worth review:

• Each watcher's stop handler clears its own refcount entry, so a consumer calling watcher.stop() directly cannot strand a count and leave the next subscription for that key permanently unstoppable.
• release() on an unknown key returns true (stop). An already-torn-down entry must not keep a watcher alive.
• unsubscribeAll() / unsubscribeAllContracts() are teardown and deliberately ignore counts. unsubscribeAll() now iterates a snapshot, because the stop handlers mutate the registry it was iterating.

Single-subscriber behaviour is unchanged: one subscribe, one unsubscribe, stopped immediately.

Verification

Beyond unit tests — verified end-to-end against a live server. Two clients streaming mainnet USDC (CCW67TSZ...), first disconnected:

=== client B, after A left ===
12551 bytes
data: {"type":"contract.emitted","contractId":"CCW67TSZ...","ledger":63854040,...}
data: {"type":"contract.emitted","contractId":"CCW67TSZ...","ledger":63854040,...}

Client B went on receiving real contract.emitted events rather than going silent.

12 new tests; all 603 existing pulse-core tests still pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orbital-dev	Ready	Preview	Aug 10, 2026 12:23am