feat: ref.live — standard signals as the read-side adapter

[cardmagic]

Implements #24.

The shape

One side-effect import enables reference.live, completing one property, three tenses:

import "solid-objects/signals"

const counter = Counter.ref("page-hits")

snapshot.count            // past: one committed read
await counter.count       // present: ask the actor now
counter.live.count        // continuous: a read-only standard signal
counter.live.snapshot     // the authorized snapshot, kept current

From Lit: watch(counter.live.count) with the SignalWatcher mixin, no glue. Any consumer of the TC39 signals API composes the same way.

Design

• Optional-peer discipline. The signals entry installs a factory into the reference core; signal-polyfill (new optional peer) never loads unless solid-objects/signals is imported, and reference.live throws a pointer to that import otherwise — the same seam pattern as the platform registration.
• Lifecycle from watched/unwatched. The first watcher opens an in-process runtime.realtime session (subscribe replays committed observables immediately); the last watcher's departure closes it after a configurable linger (configureLiveSignals). Entries dedupe per runtime and actor identity.
• Read-only by construction. Exposed signals are Signal.Computed mirrors; the package types use a structural LiveSignal { get() } so the type surface never requires the optional peer.
• The privacy model maps. Value-broadcast observables feed named signals from envelopes; invalidation-only names stay undefined by design, and live.snapshot re-fetches the authorized snapshot (coalesced) on each accepted envelope. Personalized payload projections arrive as live.payloads.<name> signals with their independent per-name revision fences; a newly watched payload name re-sends the subscription with the grown name list.
• Revision fence. Envelopes apply only on a monotonic revision advance for the same instance — the browser client's fence, one layer lower.

Tests

• 10 Vitest tests: replay into a fresh watcher, follow-on commits through the broadcast outbox, invalidation-only snapshot refresh, stale-revision rejection (using snapshotWithIncarnation for the real instance id), subscribe-on-watch and release-after-linger with a subscription-count leak check, proxy and signal identity stability with read-only enforcement, the helpful error when the entry is not imported, subscription retry after denials, canonical-entry behavior across references, and payload delivery with mid-session subscription growth.
• 1 new Playwright test (9 total pass): a WASM-runtime actor in a Chromium module worker increments while a standard signal watcher observes the committed values.
• Full suite: 334 unit tests pass; check (including the browser-import graph, which now includes src/signals.ts) passes.

Docs

docs/api.md gains the solid-objects/signals section (shape, behavior, the reserved snapshot name, the authorization note) and a reference.live bullet; docs/parity.md records the capability as JavaScript-only with the Turbo/Action Cable correspondence — Rails already fills this slot natively, which is the parity ledger's own definition working as intended; CHANGELOG.md starts the next Unreleased section.

Deviation from the RFP, recorded honestly

v1 rides runtime-backed references (Node and the browser host) rather than the thin-page realtime client: references carry their runtime, and the in-process realtime session already delivers envelopes on both platforms, so no ambient connection registry was needed. Follow-ups tracked in #24: the thin-page client variant, the optimistic layer, and the shuffleupandplay Lit demo. Payload signals landed in this PR after review.

[greptile-apps]

Greptile Summary

The PR adds an optional standard-signals adapter for actor references, backed by runtime realtime subscriptions.

• Adds stable read-only signals for observable values, authorized snapshots, and personalized payloads.
• Adds watcher-driven subscription lifecycle, retry handling, weak canonical-entry caching, and revision fences.
• Adds package exports, documentation, unit coverage, and a browser-worker integration test.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/signals.ts	Implements live signal caching, watcher lifecycle, retry recovery, payload handling, and revision-fenced updates.
src/reference.ts	Adds the typed reference.live surface and optional side-effect-installed factory seam.
test/live-signals.test.ts	Covers replay, updates, snapshot refresh, fencing, lifecycle, retries, canonical identity, payloads, and read-only behavior.
test/browser/live-signals-worker.mjs	Exercises live signals against a browser WASM runtime actor in a module worker.
package.json	Exports the signals entry point and declares signal-polyfill as an optional peer.

_{Reviews (4): Last reviewed commit: "feat: payload signals on live references" | Re-trigger Greptile}

[cardmagic]

@greptile-apps review

Both findings addressed in the latest commit: a failed subscribe now tears down its session and retries on retryMilliseconds while watchers remain (test: two denials, then recovery), and entries evict from the runtime cache on close with liveEntryCount(runtime) as the diagnostic (test: 1 watched, 0 after linger, 1 on rewatch).

[cardmagic]

@greptile-apps review

Round-two finding addressed: the registry now holds entries by WeakRef with a FinalizationRegistry sweep, so one entry stays canonical per actor for as long as any proxy or signal is reachable — competing entries cannot exist by construction — and fully abandoned entries leave the cache via GC. The regression test encodes the exact reported scenario (retained proxy + replacement reference) and asserts one subscription, one entry, and identical signal objects from both references.

[cardmagic]

@greptile-apps review