wenay-common2 1.0.66 → 1.0.68

package/doc/ROADMAP.md

@@ -35,98 +35,111 @@ This implies a useful split:
 - **API surface** remains facade-shaped and typed.
 - **Transport/routing layer** may substitute sockets and promote paths.
 - **Replay layer** resumes streams and mirrors from the last known `seq`.
-- **Authority layer** decides whether an incoming write is accepted, predicted, reconciled, or merged.
-
-Critical ordering rule: do **not** start with WebRTC/NAT plumbing or CRDTs. The next useful layer is a
-small route/account/policy coordinator with a fake/in-process transport adapter. Direct transport and
-multi-writer merge are expensive adapters; they only become safe after the coordinator state machine is
+- **Authority layer** decides whether an incoming write is accepted, predicted, reconciled, or merged.
+
+Critical ordering rule: do **not** start with WebRTC/NAT plumbing or CRDTs. The next useful layer is a
+small route/account/policy coordinator with a fake/in-process transport adapter. Direct transport and
+multi-writer merge are expensive adapters; they only become safe after the coordinator state machine is
 boring and well-tested.
 
-### 0.1 Account route coordinator ("wrapper over wrappers") 🔴
-
-Some deployments need separate client/account identities to communicate directly when policy and
-network conditions allow it, while still allowing the server/relay to step back into the path later.
-This is not just a socket trick; it is an account-aware routing shell above the existing facade,
-mirror, and replay primitives.
-
-- **Account model:** every participant has its own account/session identity and a scoped facade/store
-  set. Runtime-account maps are a dynamic keyspace, so they should look like `noStrict(accountMap)`
-  rather than a fixed schema. Access checks stay in the facade/policy layer; `noStrict` is not an ACL.
-- **Wrapper over wrappers:** an app-level coordinator owns the set of per-account clients, exposed
-  facades, mirrors, replay subscriptions, and route state. "State of other accounts" is represented as
-  selected `Observe` mirrors/replay/offline resources, ideally started and stopped through
-  `createStoreManager`, not as a new global store core.
-- **Route states:** a pair of accounts may be `relay`, `direct`, `direct+shadowRelay` (audit/observe
-  copy), `blocked`, or `fallback`. Direct links are optional optimizations, useful for latency or
-  traffic cost, not a semantic change.
-- **Re-interposition:** if NDA/privacy policy, audit, moderation, throttling, reauth, direct-link
-  failure, or group topology changes require it, the relay must be able to re-enter the data path.
-  This is the reverse of direct promotion: open the replacement route, resume from the last `seq`,
-  switch consumers after catch-up, then close or demote the old route.
-- **Privacy rule:** direct account links are opt-in and policy-gated. Peers only receive the endpoint
-  and session material needed for that specific relationship; no implicit broad account discovery.
-
-Concrete next API shape, not final names:
-
-```ts
-createRouteCoordinator({
-  policy,
-  routes,
-  resources,
-}) -> {
-  pair(a, b),
-  state(pair),
-  promoteDirect(pair, opts?),
-  reinterposeRelay(pair, reason?),
-  block(pair, reason?),
-  fallback(pair, reason?),
-  onRoute(cb),
-}
-```
-
-Policy must run **before** transport promotion:
-
-- `canDirect(pair, ctx)` - may these accounts attempt direct at all?
-- `mustRelay(pair, ctx)` - force relay path because of NDA/audit/moderation/reauth.
-- `mustShadowRelay(pair, ctx)` - allow direct payload path, but keep audit/observe copy.
-- `canExposeEndpoint(pair, ctx)` - whether signaling may reveal endpoint/session material.
-- `canReinterpose(pair, ctx)` - whether/when relay is allowed or required to step back in.
-
-Minimum state machine:
-
-- `relay` -> `direct:connecting` -> `direct` -> `relay:reinterposing` -> `relay`
-- `relay` -> `direct:connecting` -> `fallback` -> `relay`
-- `direct` -> `direct+shadowRelay`
-- any state -> `blocked`
-
-Required failure modes:
-
-- direct setup never completes: keep relay active and mark fallback;
-- replacement route catches up too slowly: keep old route active and fail the switch;
-- policy changes mid-stream: re-interpose relay through replay hand-off;
-- account reauth changes facade/ACL: rebuild route policy before accepting new writes;
-- endpoint/session material is revoked: close direct and resume relay from `seq`;
-- audit/shadow route lags: decide whether to throttle, fallback, or block by policy.
-
-Acceptance tests for 0.1:
-
-- policy denial: direct is never attempted;
-- direct promotion: old relay stays live until replacement catches up;
-- failed direct: old relay continues with no data gap;
-- re-interposition: direct -> relay resumes from `seq`;
-- `direct+shadowRelay`: direct path is active while relay/audit mirror observes;
-- revocation: direct closes and relay resumes without changing facade API;
-- account map uses `noStrict`, but all access checks live in policy/facade code;
-- `createStoreManager` starts/stops selected per-account mirrors without store-core changes.
-
-Open questions: exact policy object shape; signaling envelope; whether the relay sees payloads or only
-coordinates encrypted direct streams; app-facing route-state events; backpressure across multi-hop and
-direct paths; group topology beyond a pair of accounts.
-
-Status: 🔴 not started. This belongs to project-0 architecture: no store-core change, but it defines
-the account/routing shell that later direct-connection work plugs into. This is the next important
-roadmap item; WebRTC and CRDT work should wait until this state machine is proven with fake transports.
-
+### 0.1 Account route coordinator ("wrapper over wrappers") 🟡
+
+Some deployments need separate client/account identities to communicate directly when policy and
+network conditions allow it, while still allowing the server/relay to step back into the path later.
+This is not just a socket trick; it is an account-aware routing shell above the existing facade,
+mirror, and replay primitives.
+
+- **Account model:** every participant has its own account/session identity and a scoped facade/store
+  set. Runtime-account maps are a dynamic keyspace, so they should look like `noStrict(accountMap)`
+  rather than a fixed schema. Access checks stay in the facade/policy layer; `noStrict` is not an ACL.
+- **Wrapper over wrappers:** an app-level coordinator owns the set of per-account clients, exposed
+  facades, mirrors, replay subscriptions, and route state. "State of other accounts" is represented as
+  selected `Observe` mirrors/replay/offline resources, ideally started and stopped through
+  `createStoreManager`, not as a new global store core.
+- **Route states:** a pair of accounts may be `relay`, `direct`, `direct+shadowRelay` (audit/observe
+  copy), `blocked`, or `fallback`. Direct links are optional optimizations, useful for latency or
+  traffic cost, not a semantic change.
+- **Re-interposition:** if NDA/privacy policy, audit, moderation, throttling, reauth, direct-link
+  failure, or group topology changes require it, the relay must be able to re-enter the data path.
+  This is the reverse of direct promotion: open the replacement route, resume from the last `seq`,
+  switch consumers after catch-up, then close or demote the old route.
+- **Privacy rule:** direct account links are opt-in and policy-gated. Peers only receive the endpoint
+  and session material needed for that specific relationship; no implicit broad account discovery.
+
+Concrete next API shape, not final names:
+
+```ts
+createRouteCoordinator({
+  policy,
+  routes,
+  resources,
+}) -> {
+  pair(a, b),
+  state(pair),
+  promoteDirect(pair, opts?),
+  reinterposeRelay(pair, reason?),
+  block(pair, reason?),
+  fallback(pair, reason?),
+  onRoute(cb),
+}
+```
+
+Policy must run **before** transport promotion:
+
+- `canDirect(pair, ctx)` - may these accounts attempt direct at all?
+- `mustRelay(pair, ctx)` - force relay path because of NDA/audit/moderation/reauth.
+- `mustShadowRelay(pair, ctx)` - allow direct payload path, but keep audit/observe copy.
+- `canExposeEndpoint(pair, ctx)` - whether signaling may reveal endpoint/session material.
+- `canReinterpose(pair, ctx)` - whether/when relay is allowed or required to step back in.
+
+Minimum state machine:
+
+- `relay` -> `direct:connecting` -> `direct` -> `relay:reinterposing` -> `relay`
+- `relay` -> `direct:connecting` -> `fallback` -> `relay`
+- `direct` -> `direct+shadowRelay`
+- any state -> `blocked`
+
+Required failure modes:
+
+- direct setup never completes: keep relay active and mark fallback;
+- replacement route catches up too slowly: keep old route active and fail the switch;
+- policy changes mid-stream: re-interpose relay through replay hand-off;
+- account reauth changes facade/ACL: rebuild route policy before accepting new writes;
+- endpoint/session material is revoked: close direct and resume relay from `seq`;
+- audit/shadow route lags: decide whether to throttle, fallback, or block by policy.
+
+Acceptance tests for 0.1:
+
+- policy denial: direct is never attempted;
+- direct promotion: old relay stays live until replacement catches up;
+- failed direct: old relay continues with no data gap;
+- re-interposition: direct -> relay resumes from `seq`;
+- `direct+shadowRelay`: direct path is active while relay/audit mirror observes;
+- revocation: direct closes and relay resumes without changing facade API;
+- account map uses `noStrict`, but all access checks live in policy/facade code;
+- `createStoreManager` starts/stops selected per-account mirrors without store-core changes.
+
+Open questions: whether the relay sees payloads or only coordinates encrypted direct streams;
+backpressure across multi-hop and direct paths; group topology beyond a pair of accounts;
+`noStrict(accountMap)` / `createStoreManager` lifecycle integration for dynamic peer maps.
+
+Status: 🟡 partial (2026-07-09, v1.0.67). Core implemented as `Replay.createRouteCoordinator`
+(`src/Common/events/route-coordinator.ts`): `RouteConnector` contract (pure transport: open/close/state/
+metrics/onFail/capabilities), all five policy hooks, the full state machine above (including
+`direct+shadowRelay` audit copy, catch-up timeout, revocation auto-fallback, terminal `blocked`), data
+continuity through `replayRouteSubscribe`. Acceptance oracle: `replay/route-coordinator.test.ts` over
+fake in-process connectors — policy denial never touches transport, promotion keeps the old relay live,
+failed/slow direct falls back gap-free, re-interposition resumes from `seq`, shadow relay observes the
+switch window, revocation closes direct without facade changes, block is terminal.
+v1.0.68 added step 9: `createSignalHub` (offer/answer/ICE/session/revoke over the EXISTING socket/RPC
+control channel; `authorize` = server-side `canExposeEndpoint`), `createWebRtcConnector` /
+`acceptWebRtcDirect` (RTCPeerConnection injected as a runtime factory, structural types, no lib.dom),
+and `serveReplayChannel`/`channelReplayRemote` (replay wire over any ordered channel — the datachannel
+path bypasses the RPC core by design). Oracle `replay/route-webrtc.test.ts` drives promotion, endpoint
+denial, session rejection, and server revoke over both an in-proc hub and a real Socket.IO/RPC wire.
+Still open: browser/Node WebRTC glue (step 10 — now a one-line `rtc` factory plus media re-emit) and
+the account-map lifecycle integration (step 7).
+
 ## 1. Connection hand-off — relay ↔ direct promotion ("port forwarding") 🟡
 
 A relay/intermediary bootstraps a connection between two parties, then — on a signal — **steps out
@@ -147,10 +160,13 @@ starts flowing on the new path.
   catch it up from the last delivered `seq`, then close the old route. This covers relay → direct
   promotion and direct → relay re-interposition for any ordered `ReplayRemote`; overlap is deduped by
   `seq`, and a failed replacement leaves the old route active.
-- Open questions: signaling channel that negotiates the direct endpoint; fallback if the direct path
-  never establishes (stay on relay); auth continuity across the swap; per-socketKey vs whole-connection
-  hand-off; policy trigger and catch-up boundary for direct → relay re-interposition.
-- Status: 🟡 partial. Route hand-off/resume helper is implemented and covered by `replay/route-handoff.test.ts`; signaling, direct endpoint negotiation, NAT/WebRTC adapter, auth-continuity policy, and trigger rules remain open.
+- Open questions: auth continuity across the swap; per-socketKey vs whole-connection hand-off;
+  policy trigger rules for direct → relay re-interposition beyond explicit calls and `onFail`.
+- Status: 🟡 mostly done. Route hand-off/resume: `replay/route-handoff.test.ts`. Route decisions +
+  state machine: `createRouteCoordinator` (v1.0.67). Signaling + direct endpoint negotiation over the
+  existing control channel and fallback-if-never-establishes: `createSignalHub` /
+  `createWebRtcConnector` / `acceptWebRtcDirect` (v1.0.68, `replay/route-webrtc.test.ts`). Remaining:
+  real NAT/WebRTC runtime glue (injected `rtc` factory) and auth-continuity policy.
 
 ## 2. Coordinated fan-out send to a large group 🧊
 

package/doc/changes/1.0.67.md

@@ -0,0 +1,10 @@
+# 1.0.67
+
+- Add `Replay.createRouteCoordinator`: policy-gated relay <-> direct routing shell over pure transport connectors (ROADMAP 0.1 core).
+- Add the `RouteConnector` contract: `open/close/state`, capabilities (`binary/ordered/reliable`), route label, `metrics` (rtt/pending), and `onFail` events — connectors stay pure transports, the coordinator alone owns route decisions.
+- Route state machine: `relay -> direct:connecting -> direct | direct+shadowRelay`, re-interposition (`relay:reinterposing -> relay`), `fallback` on failed/slow/revoked direct, terminal `blocked`.
+- Policy hooks run before any transport action: `canDirect`, `mustRelay`, `mustShadowRelay`, `canExposeEndpoint`, `canReinterpose`; denial means direct is never attempted.
+- `promoteDirect({timeoutMs?})` treats policy denial and transport failure as result objects, not exceptions; a slow replacement route times out while the old route keeps flowing; direct `onFail` (endpoint revoked) auto-falls back to relay from the last `seq`.
+- `direct+shadowRelay`: payload rides direct while `shadow(ref, ...ev)` receives the relay audit copy starting from the consumers' seq coordinate (the switch window never escapes the audit).
+- Data continuity is `replayRouteSubscribe` underneath: every route change is gap-free and dup-free by the `seq` contract; consumer facade/authority semantics never learn the transport switched.
+- Add acceptance oracle `replay/route-coordinator.test.ts` over fake in-process relay/direct connectors (policy denial, promotion, failed direct, catch-up timeout, shadow relay, revocation, block, store mirror over a switched route).

package/doc/changes/1.0.68.md

@@ -0,0 +1,8 @@
+# 1.0.68
+
+- Add `Replay.createSignalHub`: WebRTC signaling (offer/answer/ICE/session/revoke envelopes) routed between accounts over the EXISTING socket/RPC control channel — the port shape `{send, signals}` is exposable by `createRpcServerAuto` as is; `authorize(env)` is the server-side `canExposeEndpoint` enforcement point, `from`-spoofing is cut at the port.
+- Add `Replay.createWebRtcConnector`: the direct `RouteConnector` for `createRouteCoordinator` — `open()` negotiates offer/answer/ICE through a signal port and returns a replay wire over the datachannel. `RTCPeerConnection` is NOT bundled: `rtc` is an injected runtime factory (browser `() => new RTCPeerConnection(cfg)`, Node werift/node-datachannel, tests an in-proc fake) over structural `RtcPeerConnection`/`RtcDataChannel` types (no lib.dom).
+- Add `Replay.acceptWebRtcDirect`: responder side — answers offers, serves `exposeReplay(...)` into the incoming datachannel; `accept(env)` validates opaque session material and rejects with a loud `revoke` so the initiator fails fast instead of timing out.
+- Add `Replay.serveReplayChannel` / `channelReplayRemote` / `channelFromDataChannel`: replay wire over any ordered string channel (datachannel/MessagePort/worker/pipe) via a tiny JSON sub/req/res protocol — no RPC core on the direct path; channel close surfaces as a non-envelope (loud `onError`), never silence.
+- Revoke/close signals and channel death during `open()` abort the pending promotion immediately (no `openTimeoutMs` wait); the coordinator auto-falls back to relay from the last `seq`.
+- Add oracle `replay/route-webrtc.test.ts`: fake in-proc RTC runtime + signaling hub (promotion, server-side endpoint denial, bad session revoke, server revoke fallback, recovery into direct) and the same signaling driven over a real Socket.IO/RPC wire.

package/doc/wenay-common2-rare.md

@@ -247,8 +247,8 @@ WebRTC future contract:
 - `transport:'webrtc'` is reserved and currently reports `state:'error'` on `start()`; it is not a hidden second transport.
 - Future WebRTC support must be explicit opt-in for sub-200ms human duplex. Signaling belongs on the existing socket/RPC control channel (offer/answer/ICE), and backend/AI access requires an SFU that re-emits media bytes into the same `Media` Listen/replay surface. Downstream RPC/replay/store consumers must not change.
 
-Oracle: `npx ts-node replay/media-socket.test.ts` checks header decode, plain Listen shape, `replay:true`, typed no-device state in Node, and real Socket.IO binary delivery.
-
+Oracle: `npx ts-node replay/media-socket.test.ts` checks header decode, plain Listen shape, `replay:true`, typed no-device state in Node, and real Socket.IO binary delivery.
+
 ## 📈 exchange — params (`CParams`)
 ```
 class CParams / CParamsReadonly implements IParams
@@ -464,8 +464,8 @@ exposeReplay(replay)  <->  replaySubscribe(remote, cb, {since?, onSeq?, staleMs?
   //   on the line (RPC_STOP — e.g. the gate's loud sacred failure) surfaces via onError + off, never silence.
   //   hint reaches the frame lambda on catch-up and on every explicit frame(seq, hint) call (pull); the push-gate's
   //   drain recovery uses the line's DEFAULT condensation — client-specific rules/pace = the pull path.
-  // off.ready (catch-up done) · off.seq() (reconnect point) · off.isStale()/off.lastTs(); reconnect = call again with {since: prev.seq()}
-replayRouteSubscribe(remote, cb, {label?, since?, onSeq?, onError?, onRoute?}) -> off & {ready, switch(nextRemote, {label?, since?, reset?, policy?, hint?}), seq(), label(), active()}
+  // off.ready (catch-up done) · off.seq() (reconnect point) · off.isStale()/off.lastTs(); reconnect = call again with {since: prev.seq()}
+replayRouteSubscribe(remote, cb, {label?, since?, onSeq?, onError?, onRoute?}) -> off & {ready, switch(nextRemote, {label?, since?, reset?, policy?, hint?}), seq(), label(), active()}
   // transport hand-off helper: old route remains live, replacement subscribes+catches up from seq, then old closes; overlap is seq-deduped. Use for relay -> direct and direct -> relay over any ordered ReplayRemote.
   // DELIVERY CONTRACT (guaranteed, not best-effort): the subscriber's cb sees ONE uniform stream —
   //   first delivery = the snapshot (keyframe as an event of the SAME type; store: root patch),
@@ -485,7 +485,58 @@ replayRouteSubscribe(remote, cb, {label?, since?, onSeq?, onError?, onRoute?}) -
   //   of clock skew) + ENVELOPE-TS AGE checked at delivery (producer clock — a stale keyframe reports stale
   //   IMMEDIATELY; clock-skew caveat: producer/client clocks may disagree, skewMs tolerance absorbs it, default 0).
   //   A since-tail's historical ts never flaps mid-catch-up (one assessment after handover); off() disarms the timer.
-exposeStoreReplay(store, opts?)  <->  syncStoreReplay(mirror, remote, opts?)            // layer B: patch line; keyframe = root patch ({path: [], value: snapshot})
+createRouteCoordinator({connect, policy?, shadow?, catchUpTimeoutMs?}) -> coordinator    // policy-gated relay <-> direct routing shell over pure connectors (ROADMAP 0.1)
+  // LAYERING: a CONNECTOR is a pure transport (no route decisions) — {info: {label, kind: 'relay'|'direct',
+  //   binary?, ordered?, reliable?}, open() -> ReplayRemote, close(), state(), metrics?() -> {rtt?, pending?},
+  //   onFail?}; the COORDINATOR alone owns promotion/fallback (state machine + policy); data continuity is
+  //   replayRouteSubscribe underneath, so ANY route change is gap-free and dup-free by the seq contract.
+  //   WebRTC/NAT is deliberately absent here: a future datachannel is just another RouteConnector.
+  // connect(ref, kind) -> RouteConnector — transport factory per pair and kind (called per activation).
+  // policy hooks run BEFORE any transport action; absent hook = allowed, present hook must return true:
+  //   canDirect (may the pair attempt direct) · mustRelay (force relay: NDA/audit/moderation — beats canDirect)
+  //   · mustShadowRelay (direct payload + relay audit copy) · canExposeEndpoint (may signaling reveal
+  //   endpoint/session material) · canReinterpose (may relay step back into the path).
+  // coordinator.pair(a, b) -> link (symmetric key: pair(a,b) == pair(b,a)) · state/promoteDirect/
+  //   reinterposeRelay/fallback/block(pairOrKey, ...) · onRoute(cb) -> off (all transitions, all pairs)
+  //   · pairs() · close()
+  // link: .subscribe(cb, opts?) -> off & {ready, seq(), label(), active()}   // the pair's data: a replay stream
+  //     that survives every route change; facade/authority semantics never learn the transport switched
+  //   .promoteDirect({timeoutMs?, reason?}) -> Promise<{ok, state, reason?}>  // policy denial and transport
+  //     failure are EXPECTED OUTCOMES (result object), not exceptions; ops are serialized per link
+  //   .reinterposeRelay(reason?) / .fallback(reason?) / .block(reason?) · .state() · .label() · .metrics() · .close()
+  // STATE MACHINE: relay -> direct:connecting -> direct | direct+shadowRelay; direct -> relay:reinterposing -> relay;
+  //   failed/slow direct (timeoutMs) -> fallback (relay kept live the whole time, switch failed loudly);
+  //   direct onFail (endpoint revoked, link died) -> auto fallback: close direct, resume relay from seq;
+  //   any state -> blocked (terminal: subs closed, new subscribe throws, promote denied).
+  // direct+shadowRelay: payload rides direct while deps.shadow(ref, ...ev) receives the relay audit copy,
+  //   starting from the consumers' seq coordinate — the switch window never escapes the audit.
+  // Acceptance oracle: replay/route-coordinator.test.ts (fake in-process relay/direct connectors).
+createSignalHub({authorize?}) -> {register(account) -> {send, signals, close}, revoke(pair, accounts, reason?), accounts(), close()}
+  // WebRTC signaling over the EXISTING control channel: the port shape {send, signals} is a function +
+  //   Listen — exactly what createRpcServerAuto exposes, so the relay socket IS the signaling wire
+  //   (per connection: const port = hub.register(account); object = {send: port.send, signals: port.signals}).
+  // authorize(env) is the SERVER-side canExposeEndpoint point — endpoint/session material is revealed only
+  //   past it; client-side coordinator policy stays advisory. from-spoofing is cut at the port.
+  // SignalEnvelope = {type: 'offer'|'answer'|'ice'|'revoke'|'close', pair, from, to, sdp?, candidate?,
+  //   session?, reason?} — session is opaque auth material (the wire never looks inside).
+createWebRtcConnector({port, rtc, self, peer, pair, session?, label?, openTimeoutMs?}) -> RouteConnector
+  // the direct connector for createRouteCoordinator: open() drives offer/answer/ICE through the signal
+  //   port, waits for the datachannel, returns a replay wire over it. RTCPeerConnection is NOT bundled:
+  //   rtc is a runtime factory — browser `() => new RTCPeerConnection(cfg)`, Node werift/node-datachannel,
+  //   tests an in-proc fake (RtcPeerConnection/RtcDataChannel are structural types, no lib.dom).
+  //   revoke/close signals and channel death (incl. DURING open) fail loudly -> coordinator auto-fallback.
+acceptWebRtcDirect({port, rtc, self, serve, accept?}) -> close()
+  // responder side: on offer, negotiates answer/ICE and serves serve(env) (exposeReplay(...) as is) into
+  //   the incoming datachannel; accept(env) validates session material and rejects with a loud revoke
+  //   (the initiator fails fast, not by timeout). Repeated offer for a pair recreates the session.
+serveReplayChannel(source, channel) <-> channelReplayRemote(channel) -> ReplayRemote
+  // replay wire over ANY ordered string channel (datachannel/MessagePort/worker/pipe): tiny JSON
+  //   sub/req/res protocol, no RPC core — a direct channel lives OUTSIDE the main rpc connection.
+  //   Channel close = non-envelope (null) on the line: replay subscribers report onError, never silence.
+  //   ReplayMessageChannel = {send, onMessage, onClose?, close?}; channelFromDataChannel(dc) adapts a
+  //   datachannel (and owns its handlers). Oracle: replay/route-webrtc.test.ts (fake RTC runtime +
+  //   in-proc hub + the same signaling over a real Socket.IO/RPC wire).
+exposeStoreReplay(store, opts?)  <->  syncStoreReplay(mirror, remote, opts?)            // layer B: patch line; keyframe = root patch ({path: [], value: snapshot})
 syncStoreReplayRoute(mirror, remote, opts?) -> off & {ready, switch(nextRemote, opts), seq(), label(), active()}   // same patch fold, but route-replaceable for relay/direct promotion
 syncStoreReplayEach<T>(remote, cb, opts?) -> off & {store, ready, seq(), isStale(), lastTs()}   // one-call per-key fold over the patch line (mirror + syncStoreReplay + store.each()); most-used surface — full contract + example in wenay-common2.md
 createOfflineStore({key, remote?, initial, storage, version?, debounceMs?, syncOpts?}) -> Promise<OfflineStore<T>>

package/lib/Common/events/replay-channel.d.ts

@@ -0,0 +1,9 @@
+import { ReplayRemote } from './replay-wire';
+export type ReplayMessageChannel = {
+    send: (data: string) => void;
+    onMessage: (cb: (data: string) => void) => (() => void) | void;
+    onClose?: (cb: () => void) => (() => void) | void;
+    close?: () => void;
+};
+export declare function serveReplayChannel<Z extends any[]>(source: ReplayRemote<Z>, channel: ReplayMessageChannel): () => void;
+export declare function channelReplayRemote<Z extends any[]>(channel: ReplayMessageChannel): ReplayRemote<Z>;

package/lib/Common/events/replay-channel.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveReplayChannel = serveReplayChannel;
+exports.channelReplayRemote = channelReplayRemote;
+function unsubscribeHandle(handle) {
+    if (typeof handle == 'function') {
+        handle();
+        return;
+    }
+    if (typeof handle?.off == 'function')
+        handle.off();
+    else if (typeof handle?.unsubscribe == 'function')
+        handle.unsubscribe();
+}
+function serveReplayChannel(source, channel) {
+    let lineOff = null;
+    let closed = false;
+    async function handleRequest(msg) {
+        try {
+            const v = msg.m == 'since' ? await source.since(msg.a[0])
+                : msg.m == 'keyframe' ? await source.keyframe()
+                    : msg.m == 'frame' ? (source.frame ? await source.frame(msg.a[0], msg.a[1]) : null)
+                        : undefined;
+            if (!closed)
+                channel.send(JSON.stringify({ t: 'res', id: msg.id, ok: true, v: v ?? null }));
+        }
+        catch (e) {
+            if (!closed)
+                channel.send(JSON.stringify({ t: 'res', id: msg.id, ok: false, e: String(e) }));
+        }
+    }
+    const offMsg = channel.onMessage(function onReplayChannelMessage(raw) {
+        if (closed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (msg?.t == 'sub' && !lineOff) {
+            lineOff = source.line.on(function forwardEnvelope(ev) {
+                if (!closed)
+                    channel.send(JSON.stringify({ t: 'ev', ev }));
+            });
+            return;
+        }
+        if (msg?.t == 'req')
+            void handleRequest(msg);
+    });
+    function close() {
+        if (closed)
+            return;
+        closed = true;
+        unsubscribeHandle(lineOff);
+        lineOff = null;
+        if (typeof offMsg == 'function')
+            offMsg();
+    }
+    channel.onClose?.(close);
+    return close;
+}
+function channelReplayRemote(channel) {
+    let nextId = 1;
+    let subscribed = false;
+    let closed = false;
+    const pending = new Map();
+    const lineCbs = new Set();
+    channel.onMessage(function onRemoteChannelMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (msg?.t == 'ev') {
+            for (const cb of Array.from(lineCbs))
+                cb(msg.ev);
+            return;
+        }
+        if (msg?.t == 'res') {
+            const p = pending.get(msg.id);
+            pending.delete(msg.id);
+            if (!p)
+                return;
+            if (msg.ok)
+                p.resolve(msg.v);
+            else
+                p.reject(new Error(msg.e ?? 'replay channel request failed'));
+        }
+    });
+    channel.onClose?.(function onRemoteChannelClosed() {
+        if (closed)
+            return;
+        closed = true;
+        for (const [, p] of pending)
+            p.reject(new Error('replay channel closed'));
+        pending.clear();
+        for (const cb of Array.from(lineCbs))
+            cb(null);
+        lineCbs.clear();
+    });
+    function req(m, a) {
+        if (closed)
+            return Promise.reject(new Error('replay channel closed'));
+        return new Promise((resolve, reject) => {
+            const id = nextId++;
+            pending.set(id, { resolve, reject });
+            channel.send(JSON.stringify({ t: 'req', id, m, a }));
+        });
+    }
+    return {
+        line: {
+            on(cb) {
+                lineCbs.add(cb);
+                if (!subscribed && !closed) {
+                    subscribed = true;
+                    channel.send(JSON.stringify({ t: 'sub' }));
+                }
+                return function offChannelLine() { lineCbs.delete(cb); };
+            },
+        },
+        since: seq => req('since', [seq]),
+        keyframe: () => req('keyframe', []),
+        frame: (seq, hint) => req('frame', [seq, hint]),
+    };
+}

package/lib/Common/events/replay-index.d.ts

@@ -3,3 +3,6 @@ export * from './replay-wire';
 export * from './replay-conflate';
 export * from './replay-history';
 export * from './replay-route';
+export * from './route-coordinator';
+export * from './replay-channel';
+export * from './route-signal-webrtc';

package/lib/Common/events/replay-index.js

@@ -19,3 +19,6 @@ __exportStar(require("./replay-wire"), exports);
 __exportStar(require("./replay-conflate"), exports);
 __exportStar(require("./replay-history"), exports);
 __exportStar(require("./replay-route"), exports);
+__exportStar(require("./route-coordinator"), exports);
+__exportStar(require("./replay-channel"), exports);
+__exportStar(require("./route-signal-webrtc"), exports);