wenay-common2 1.0.65 → 1.0.67

package/CLAUDE.md

@@ -51,6 +51,26 @@ Write new code in this style by default — no need to ask.
 ## Comments
 - Section dividers like `// ===...===` with a block heading.
 - Explain "why", not "what". Keep them short.
+
+## Work progress files
+
+- For any task that is more than a tiny/local edit, create a temporary progress file before
+  starting broad changes.
+- Put progress files under `doc/progress/`. This is the working-doc area, separate from public
+  API docs, roadmap docs, and release notes.
+- Name them by task, for example `doc/progress/replay-route-handoff.md`.
+- Keep the file short: goal, current checkpoint list, notable decisions, blockers, and verification
+  already run or still needed.
+- Update the progress file as checkpoints are completed, especially before switching context or
+  making broad edits.
+- When the task is finished, delete the progress file. Preserve only the durable outcome:
+  final response, commit message, and, for publishable changes, the matching `doc/changes/<version>.md`
+  entry.
+- If work is paused or blocked locally, leave the progress file in place and make the next required
+  action explicit. If the paused state must be committed or handed off, promote the useful part into
+  a durable doc (`ROADMAP`, `RECOMMENDATIONS`, `doc/target`, or `doc/changes`) instead of relying on
+  an ignored progress file.
+
 ## Documentation and release notes
 
 - `README.md` is navigation only. Do not put API guides, examples, or long explanations there.

package/doc/ROADMAP.md

@@ -37,7 +37,12 @@ This implies a useful split:
 - **Replay layer** resumes streams and mirrors from the last known `seq`.
 - **Authority layer** decides whether an incoming write is accepted, predicted, reconciled, or merged.
 
-### 0.1 Optional account-to-account route plane ("wrapper over wrappers") 🔴
+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.
@@ -61,12 +66,73 @@ mirror, and replay primitives.
 - **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.
 
-Open questions: account ACL/policy shape; signaling format; whether the relay sees payloads or only
-coordinates encrypted direct streams; how route state is exposed to the app; backpressure across
-multi-hop and direct paths; revocation in the middle of a live stream.
-
-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.
+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: signaling envelope; 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. Still open: real
+signaling adapter + WebRTC connector (steps 9-10 of `doc/target/webrtc-route-coordinator-tasks.md`) and
+the account-map lifecycle integration.
 
 ## 1. Connection hand-off — relay ↔ direct promotion ("port forwarding") 🟡
 

package/doc/changes/1.0.65.md

@@ -4,4 +4,5 @@
 - Add `Observe.syncStoreReplayRoute` for store mirrors that can switch relay/direct routes without gaps or duplicate patch delivery.
 - Add `replay/route-handoff.test.ts` covering relay -> direct promotion, direct -> relay re-interposition, failed replacement fallback, and store mirror convergence.
 - Update roadmap/replay docs to mark connection hand-off as partially implemented and keep signaling/WebRTC/policy triggers explicitly open.
-- Normalize package metadata for `wenay-common2@1.0.65`.
+- Normalize package metadata for `wenay-common2@1.0.65`.
+- Add `doc/progress/` working-checkpoint rules for non-trivial tasks and keep task progress files out of package output.

package/doc/changes/1.0.66.md

@@ -0,0 +1,8 @@
+# 1.0.66
+
+- Add `Media.createAudioSource` and `Media.createVideoSource` browser capture helpers that expose media as ordinary binary `Listen` sources.
+- Add fixed-header media frame helpers: `Media.encodeMediaFrame` and `Media.decodeMediaFrame` (`Uint8Array` header + raw payload, no JSON envelope).
+- Add optional `replay:true` media source mode so `createRpcServerAuto` can expose media listeners with legacy + replay surfaces under the same key.
+- Add `wenay-common2/media` package export and root `Media` namespace export.
+- Add `replay/media-socket.test.ts` covering media binary frame headers, no-device typed state, replay media source shape, and real Socket.IO/RPC binary delivery.
+- Document media-over-socket backpressure defaults and reserve WebRTC as a future explicit SFU/signaling opt-in, not the default transport.

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/wenay-common2-rare.md

@@ -205,6 +205,50 @@ Contract:
 - Static dotted keys are also supported: `api["a.b"].c` is distinct from `api.a.b.c`. Internal route/listen/cache identity must stay lossless; dotted strings are only a debug display form.
 - If a branch is a fixed public API, keep it strict. If a branch is a personal/dynamic keyspace, wrap that branch in `noStrict` instead of trying to publish all current keys as schema.
 
+## 🎙️ Media over socket — browser capture as binary Listen
+> `import { Media } from "wenay-common2"` or `import * as Media from "wenay-common2/media"`.
+> The hot path event is ONE `Uint8Array`: fixed 40-byte common2 media header + raw payload. No JSON envelope.
+```
+Media.createAudioSource(opts?) -> [emit, listen] & control
+Media.createVideoSource(opts?) -> [emit, listen] & control
+Media.encodeMediaFrame(meta, payload) -> Uint8Array
+Media.decodeMediaFrame(frame) -> {kind, codec, seq, tMono, payload, sampleRate?, channels?, nSamples?, width?, height?}
+
+control: start() -> Promise<MediaSourceState> · stop() · getStats() · setDevice(id) · listDevices()
+state: 'idle'|'requesting'|'live'|'denied'|'no-device'|'error'
+```
+Audio source:
+- default `mode:'pcm'`, `format:'int16'`, raw PCM payload; uses `AudioWorklet` when available and falls back to `ScriptProcessor` only when the browser cannot run a worklet.
+- `mode:'record'` uses `MediaRecorder` chunks (`webm-opus`) for record/upload flows, not live STT.
+- `getStats().rms` gives a VU-meter signal; permission denied/no device returns typed state, not a thrown public failure.
+
+Video source:
+- default snapshots, not a 30fps video stream: `video->canvas`, JPEG, `fps` default 3, `quality` default 0.82.
+- each frame carries absolute image bytes, so `replay:true` can safely keep the latest frame for lag recovery.
+- `worker` is API-reserved; current implementation stays main-thread. Any future worker path must transfer `ArrayBuffer` payloads, never structured-clone frame objects.
+
+Replay/RPC wiring:
+```ts
+const audio = Media.createAudioSource({sourceId: 'mic'})                 // plain lossless queue Listen
+const video = Media.createVideoSource({sourceId: 'cam', fps: 2, replay: true})
+
+createRpcServerAuto({
+    socket, socketKey: 'media',
+    object: {audio: audio[1], video: video[1]},
+    replayOpts: {highWater: 64, lowWater: 8},
+})
+```
+`replay:true` makes the returned listen a `Replay.replayListen` surface before capture emits into it, so `createRpcServerAuto` brand-detects it and exposes legacy + replay under the same key. Defaults differ by media kind: audio replay is a sacred queue (`history:1024`, no keyframe/frame, do not drop samples); video replay is keep-latest (`history:256`, `current:'last'`, `frame` returns the newest covered frame). Pass `replay:{...}` for custom history/current/frame.
+
+Backpressure rule: audio consumers should use the default queue policy unless the app explicitly accepts loss. Video consumers can use `Replay.replaySubscribe(remote.video, cb, {policy:'frame'})`; a slow socket drains to the latest frame instead of accumulating stale images. The binary frame itself is RPC-safe because `rpc-walk` passes `TypedArray`/`ArrayBuffer` leaves through natively and applies `maxBinaryLen`.
+
+WebRTC future contract:
+- `transport:'socket'` is the implemented default today.
+- `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.
+
 ## 📈 exchange — params (`CParams`)
 ```
 class CParams / CParamsReadonly implements IParams
@@ -420,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),
@@ -441,7 +485,33 @@ 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).
+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/doc/wenay-common2.md

@@ -143,6 +143,17 @@ await l.ticks.frame(mySeq)                                // pull at YOUR pace (
 // full guide + examples → rpc.md; frame model / lag policies → 🎞️ recipe below and rare docs
 ```
 
+## 🎙️ Media over socket — binary Listen frames
+```
+import { Media } from "wenay-common2"        // or: import * as Media from "wenay-common2/media"
+
+Media.createAudioSource({format?: 'int16'|'float32', mode?: 'pcm'|'record', replay?}) -> [emit, listen] & control
+Media.createVideoSource({fps? = 3, codec? = 'jpeg', quality?, replay?}) -> [emit, listen] & control
+control: start() -> Promise<'idle'|'requesting'|'live'|'denied'|'no-device'|'error'> · stop() · getStats() · setDevice(id) · listDevices() · state
+Media.encodeMediaFrame(meta, payload) / Media.decodeMediaFrame(frame)     // one Uint8Array = 40-byte fixed header + raw payload
+```
+Audio default is PCM frames from `AudioWorklet` where available (`mode:'record'` uses MediaRecorder chunks). Video default is camera snapshots (`video->canvas`, JPEG, low fps for vision). Put `listen` into `createRpcServerAuto` like any other Listen; with `replay:true`, the returned listen is a replay line, so RPC auto exposes legacy + replay surfaces under the same key. Backpressure policy: audio is lossless queue; video `replay:true` defaults to keep-latest frame recovery. `transport:'webrtc'` is reserved for a future SFU/signaling adapter; socket binary is the default today.
+
 ## 🔁 Observe — reactive state + store/mirror API
 > `import { Observe } from "wenay-common2"` or `import * as Observe from "wenay-common2/observe"`.
 > This is the documented v2 reactive/store surface.

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

@@ -3,3 +3,4 @@ export * from './replay-wire';
 export * from './replay-conflate';
 export * from './replay-history';
 export * from './replay-route';
+export * from './route-coordinator';

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

@@ -19,3 +19,4 @@ __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);

package/lib/Common/events/route-coordinator.d.ts

@@ -0,0 +1,274 @@
+import { Listener } from './Listen';
+import { ReplayRemote } from './replay-wire';
+import { ReplayRouteSubscribeOpts } from './replay-route';
+export type tRouteKind = 'relay' | 'direct';
+export type tConnectorState = 'idle' | 'opening' | 'open' | 'closed' | 'failed';
+export type RouteConnectorInfo = {
+    label: string;
+    kind: tRouteKind;
+    binary?: boolean;
+    ordered?: boolean;
+    reliable?: boolean;
+};
+export type RouteConnectorMetrics = {
+    rtt?: number;
+    pending?: number;
+};
+export type RouteConnector<Z extends any[] = any[]> = {
+    info: RouteConnectorInfo;
+    open: () => Promise<ReplayRemote<Z>> | ReplayRemote<Z>;
+    close: () => void;
+    state: () => tConnectorState;
+    metrics?: () => RouteConnectorMetrics;
+    onFail?: {
+        on: (cb: (reason?: unknown) => void) => any;
+    };
+};
+export type RoutePairRef = {
+    a: string;
+    b: string;
+    key: string;
+};
+export type RoutePolicyCtx = RoutePairRef & {
+    state: tRouteState;
+    reason?: unknown;
+};
+type tPolicyHook = (ctx: RoutePolicyCtx) => boolean | Promise<boolean>;
+export type RoutePolicy = {
+    canDirect?: tPolicyHook;
+    mustRelay?: tPolicyHook;
+    mustShadowRelay?: tPolicyHook;
+    canExposeEndpoint?: tPolicyHook;
+    canReinterpose?: tPolicyHook;
+};
+export type tRouteState = 'relay' | 'direct:connecting' | 'direct' | 'direct+shadowRelay' | 'relay:reinterposing' | 'fallback' | 'blocked' | 'closed';
+export type RouteChangeEvent = RoutePairRef & {
+    from: tRouteState;
+    to: tRouteState;
+    reason?: unknown;
+};
+export type RouteOpResult = {
+    ok: boolean;
+    state: tRouteState;
+    reason?: unknown;
+};
+export type PromoteDirectOpts = {
+    timeoutMs?: number;
+    reason?: unknown;
+};
+export type RouteCoordinatorDeps<Z extends any[] = any[]> = {
+    policy?: RoutePolicy;
+    connect: (ref: RoutePairRef, kind: tRouteKind) => RouteConnector<Z>;
+    shadow?: (ref: RoutePairRef, ...ev: Z) => void;
+    catchUpTimeoutMs?: number;
+};
+export declare function createRouteCoordinator<Z extends any[] = any[]>(deps: RouteCoordinatorDeps<Z>): {
+    pair(a: string, b: string): {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    };
+    state: (pairOrKey: {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    } | RoutePairRef | string) => tRouteState;
+    promoteDirect: (pairOrKey: {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    } | RoutePairRef | string, opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+    reinterposeRelay: (pairOrKey: {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    } | RoutePairRef | string, reason?: unknown) => Promise<RouteOpResult>;
+    fallback: (pairOrKey: {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    } | RoutePairRef | string, reason?: unknown) => Promise<RouteOpResult>;
+    block: (pairOrKey: {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    } | RoutePairRef | string, reason?: unknown) => Promise<RouteOpResult>;
+    onRoute: (cb: (ev: RouteChangeEvent) => void) => import("./Listen").ListenOff;
+    pairs: () => {
+        ref: RoutePairRef;
+        state: () => tRouteState;
+        reason: () => unknown;
+        label: () => string;
+        metrics: () => {
+            relay: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+            direct: {
+                rtt?: number;
+                pending?: number;
+                state: tConnectorState;
+            } | null;
+        };
+        subscribe: (cb: Listener<Z>, opts?: Omit<ReplayRouteSubscribeOpts, "label">) => (() => void) & {
+            ready: Promise<void>;
+            seq: () => number;
+            label: () => string | undefined;
+            active: () => boolean;
+        };
+        promoteDirect: (opts?: PromoteDirectOpts) => Promise<RouteOpResult>;
+        reinterposeRelay: (reason?: unknown) => Promise<RouteOpResult>;
+        fallback: (reason?: unknown) => Promise<RouteOpResult>;
+        block: (reason?: unknown) => Promise<RouteOpResult>;
+        close: () => void;
+    }[];
+    close(): void;
+};
+export type RouteCoordinator<Z extends any[] = any[]> = ReturnType<typeof createRouteCoordinator<Z>>;
+export type RouteLink<Z extends any[] = any[]> = ReturnType<RouteCoordinator<Z>['pair']>;
+export {};