wire-mesh-core 4.2.0 → 4.2.2

package/dist/domain/webrtc-signaling.d.mts

@@ -1,5 +1,5 @@
 import { H as ManageCommandParams, Lt as SfuTrackEntry, Rt as SfuTrackMap, V as ManageCommand, an as WebrtcAnswer, f as CapabilityScope, on as WebrtcIceCandidate, sn as WebrtcOffer, z as IceCandidateInit } from "../protocol-Cb3BnuTL.mjs";
-import { IncomingManageRequest } from "./mesh-session.mjs";
+import { d as IncomingManageRequest } from "../mesh-session-DzcZYdhe.mjs";
 import { VerifyCapabilityTokenOptions } from "./tokens.mjs";
 //#region src/domain/webrtc-signaling.d.ts
 /** The one capability verb gating every core/webrtc message shape: an authority over this node's own signaling as a whole, not three separate resources, mirroring how core/exec's exec:pty gates all of its own inner verbs. webrtc.sfu-track-map is gated by this same verb (see spec/webrtc.cddl's own comment): an SFU able to shape a negotiation can already misreport whose media is on which mid, so a separate capability over the track-map itself would guard nothing a client doesn't already have to trust the SFU for. */

package/dist/mesh-session-By06Mnu-.d.cts

@@ -0,0 +1,174 @@
+import { D as DeviceId, E as DataRequestFrame, N as Frame, T as DataHaveFrame, U as ManageError, V as ManageCommand, W as ManageOk, bt as RevocationEntry, et as PeerAdvert, f as CapabilityScope, g as CoordinatorFrame, lt as ProtocolVersion, nn as TopologyPeers, p as CapabilityToken, w as DataEntriesFrame } from "./protocol-Cb3BnuTL.cjs";
+import { r as Transport, t as Connection } from "./transport-DaeS9N-o.cjs";
+import { r as IdentityPort } from "./identity-CQof0iEM.cjs";
+import { t as Clock } from "./clock-DhUPRfLh.cjs";
+//#region src/domain/local-fault.d.ts
+/** What `onFault` is told besides the error. */
+interface FaultContext {
+  /** The peer the failing hello or send was for, when it is known by then. */
+  readonly peer: DeviceId | undefined;
+  /** How many reports for this peer were withheld since the last one: the shared fault reporter makes at most one report per peer per interval and counts the rest. */
+  readonly suppressed: number;
+}
+/** What the owner of a session hears of failures local to this side: the error, and which peer it was for and how many reports for that peer were withheld. */
+type LocalFaultHandler = (error: unknown, context: FaultContext) => void | Promise<void>;
+//#endregion
+//#region src/domain/mesh-session.d.ts
+/** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
+declare const HANDSHAKE_TIMEOUT_MS = 3000;
+type ConnectionState = {
+  status: "idle";
+} | {
+  status: "connecting";
+  address: string;
+} | {
+  status: "connected";
+  address: string;
+  handshake: HandshakeStatus;
+} | {
+  status: "reconnecting";
+  address: string;
+  attempt: number;
+  reason: string;
+} | {
+  status: "closed";
+  address: string;
+  reason: string;
+};
+/** Opt-in retry behaviour for a session's own reconnect attempts. Left at its default `null` in createMeshSession, a disconnect always falls straight to `"closed"` -- today's exact behaviour, unchanged unless a caller opts in. */
+interface ReconnectPolicy {
+  maxAttempts: number;
+  /** Backoff before attempt N (1-indexed), in milliseconds. */
+  delayMs: (attempt: number) => number;
+}
+/** The union `manage-response-frame.outcome` actually carries -- no dedicated generated type name exists for it. */
+type ManageOutcome = ManageOk | ManageError;
+/** One `manage-request` this session received from its peer, surfaced for the caller to act on and answer. */
+interface IncomingManageRequest {
+  requestId: number;
+  command: ManageCommand;
+  scope: CapabilityScope;
+  token?: CapabilityToken;
+  /** The device-id of the peer this request was relayed on behalf of, as the end-to-end secure channel it arrived through authenticated it (spec/secure-channel.cddl): the identity that channel's handshake proved, never the `from-device` a hub stamps on relay-data, which a hub can set to anything. Present only when the request arrived through a relay pairing. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. */
+  fromDevice?: DeviceId;
+  /** The device-id this request's relay-data frame was explicitly addressed to, read from its own `to-device` field -- present only when the request arrived relay-wrapped and the frame carried one. A caller fronting more than one locally-addressable device behind a single hub connection (a gateway advertising several local peers through the same relay pairing) uses this to decide whether the request is for this device or should be routed on to a different local peer it also advertises; this session has no such routing logic of its own, since it represents exactly one identity. */
+  toDevice?: DeviceId;
+  respond: (outcome: ManageOutcome) => Promise<void>;
+}
+/** The core/data frames: the raw have, request and entries primitive data-sync.ts answers. */
+type DataDomainFrame = DataHaveFrame | DataRequestFrame | DataEntriesFrame;
+/** One core/data frame this session received, surfaced for the application's replication policy to answer. */
+interface IncomingDataFrame {
+  frame: DataDomainFrame;
+  /** The device-id of the peer that sent this frame through a relay pairing, as the end-to-end secure channel it arrived through authenticated it (spec/secure-channel.cddl), never the `from-device` a hub stamps. Absent for a frame that arrived directly on the connection, whose sender is the connection's own peer. A reply goes back to this device through sendDataFrame's targetDevice. */
+  fromDevice?: DeviceId;
+  /** The device-id the frame's relay-data was addressed to, for a caller fronting several local devices behind one hub connection, exactly as IncomingManageRequest.toDevice. Present only for a relayed frame that carried one. */
+  toDevice?: DeviceId;
+}
+type HandshakeStatus = {
+  status: "pending";
+} | {
+  status: "negotiated";
+  version: ProtocolVersion;
+  sharedDomains: string[];
+} | {
+  status: "unanswered";
+} | {
+  status: "rejected";
+  reason: string;
+};
+interface SessionEvent {
+  state: ConnectionState;
+  /** The peer directory as of this event: latest peer-advert per device-id, in first-heard order. */
+  directory: readonly DirectoryEntry[];
+  /** The most recent frames that crossed the connection, sent or received, in order: at most FRAME_LOG_WINDOW entries, the recent-activity window a console shows rather than a session history. */
+  frameLog: readonly FrameLogEntry[];
+}
+interface DirectoryEntry {
+  device: DeviceId;
+  advert: PeerAdvert;
+}
+/**
+ * How many entries a session's frameLog keeps: the log exists for a console's
+ * recent-activity view, not as a session history, so it holds the most recent
+ * window of frames rather than every frame a long-lived session ever crossed.
+ * Without the bound, a busy session (a relay hub pairing, or any peer on a
+ * chatty mesh) retains every frame for its whole life, which on an
+ * always-on node grows without limit.
+ */
+declare const FRAME_LOG_WINDOW = 256;
+interface FrameLogEntry {
+  direction: "sent" | "received";
+  frame: Frame;
+}
+interface MeshSession {
+  readonly events: AsyncIterable<SessionEvent>;
+  /** Every `manage-request` received from the peer, in arrival order. */
+  readonly incomingManageRequests: AsyncIterable<IncomingManageRequest>;
+  /** Every core/data frame received, direct or through a relay pairing, in arrival order. A relayed one arrives only when it opened under the secure channel of the device that sent it, and names that device in `fromDevice`. What a frame means, and what to answer, is data-sync.ts's and the application's business, so the session only delivers it. */
+  readonly incomingDataFrames: AsyncIterable<IncomingDataFrame>;
+  /** Every `revocation-entry` received from the peer, in arrival order -- a `revocation-announce` frame's own `entries` array is flattened to one item per entry, since each entry is independently verifiable and independently meaningful regardless of which frame carried it. A consumer typically feeds each one into a RevocationView's own `record`. */
+  readonly revocationAnnouncements: AsyncIterable<RevocationEntry>;
+  /** Every `coordinator-frame` received from the peer, in arrival order: a gossiped, term-based claim to the rendezvous role (spec/transport.cddl), surfaced raw exactly like revocationAnnouncements because what a claim means is coordinator-election.ts's own business, not the session's. A consumer feeds each one into a CoordinatorElection's evaluate, and sends its own claims with sendCoordinatorClaim. */
+  readonly coordinatorFrames: AsyncIterable<CoordinatorFrame>;
+  connect: (address: string, localDomains: readonly string[]) => Promise<void>;
+  sendPing: () => Promise<void>;
+  /**
+   * Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives.
+   *
+   * The pairing is FIFO because ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's promise resolves against the Nth pong received after it, never matched by any other means.
+   *
+   * Rejects with a plain Error if the connection closes, and with a PingTimeoutError (from ping-round-trips.ts) when `timeoutMs` is given and no pong arrives within it, so a caller can tell an unanswered ping from a dropped connection. It never resolves a sentinel the way sendManageRequest's own timeout does, because there is no natural "no answer" value for a bare millisecond count to double as.
+   *
+   * Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong, which today means relay-hub's own frame handling (wire-mesh#181). Called against a plain peer that never sends pong it hangs until `timeoutMs` if given, or forever.
+   *
+   * It exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time it over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg.
+   */
+  sendPingMeasureRtt: (timeoutMs?: number) => Promise<number>;
+  /** Attaches this token to every `manage-request` sent from now on. */
+  setToken: (token: CapabilityToken) => void;
+  /** Announces one or more already-minted revocation-entries to the peer. Sent directly over the connection, never relay-wrapped -- revocation-announce is a gossiped broadcast, not a request addressed to a specific peer, so it has no targetDevice/token parameters the way sendManageRequest does. */
+  sendRevocationAnnounce: (entries: readonly RevocationEntry[]) => Promise<void>;
+  /** Sends one coordinator-frame directly over this session's own connection, never relay-wrapped: the claim is a gossiped broadcast like revocation-announce, not a request addressed to a specific peer. The frame itself comes from a CoordinatorElection (claim, or announceCurrent for a refresh), so the session never invents a term on its own. */
+  sendCoordinatorClaim: (frame: Readonly<CoordinatorFrame>) => Promise<void>;
+  /** Re-sends this side's own self-advert with a fresh snapshot-seconds and, when given, extensions merged onto peer-advert's own open `* tstr => any` tail -- the mechanism a caller uses to keep gossiped presence status (or any other advertised fact) live over a connection's lifetime, since the initial self-advert wireUpConnection sends at connect time is otherwise never repeated. Callers own their own re-advertisement cadence (there is no timer inside MeshSession itself, matching its own DOM-free, fully unit-testable design); a caller not calling this again after connecting is exactly today's existing gossip-once-on-connect behaviour. */
+  sendGossipUpdate: (extensions?: Record<string, unknown>) => Promise<void>;
+  /** This session's own current topology snapshot -- the identical `topology/peers` value buildSelfAdvert merges into every gossiped self-advert (wire-mesh#180), read back directly rather than only from a possibly-stale gossiped copy elsewhere in the mesh. The live, cache-bust half of the cached-vs-live split `topology.get` itself establishes: a caller answering an incoming topology.get manage-request (see topology.ts's createTopologyGetHandler) calls this to build the response. Synchronous and side-effect-free -- unlike every other method here, it sends nothing and works even before this session has ever connected (an unconnected session simply has no direct peer and no relay pairings yet, both honestly empty). */
+  getTopologyPeers: () => TopologyPeers;
+  /** Sends one core/data frame (data-have, data-request, or data-entries): the transport half of an application's own noticeboard replication policy (data-sync.ts owns what the frames MEAN; this owns getting one onto the wire), the same layering sendRevocationAnnounce already established for its own frame kind. Without targetDevice it goes directly over this session's own connection, never relay-wrapped, which is how a hub's mailbox is addressed. With targetDevice it is routed to that specific peer through a relay pairing, sealed on the secure channel with that device like a manage-request (spec/secure-channel.cddl), so two devices that reach each other only through a hub can run the data-domain exchange; the hub sees ciphertext and its mailbox is not involved. The peer's own frames come back through incomingDataFrames. Rejects when not connected, exactly like every other send method here. */
+  sendDataFrame: (frame: DataDomainFrame, targetDevice?: DeviceId) => Promise<void>;
+  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. When timeoutMs is given, the returned promise resolves with `{ result: "error", code: "timeout" }` rather than hanging forever if no manage-response arrives in time -- a held-open request (a human approval, a not-yet-online peer) otherwise has no way for the caller to give up on it. Absent, this request waits exactly as before, with no time limit of its own. */
+  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken, timeoutMs?: number) => Promise<ManageOutcome>;
+  close: () => Promise<void>;
+}
+declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null,
+/** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert so other peers can attempt a direct connection instead of always falling back to a relay. Omit (or pass none) for a caller with nothing to offer, e.g. a browser client. */
+addresses?: readonly string[],
+/** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- the hook a gossip-expansion consumer (wire-mesh#187, gossip-expansion.ts's own createGossipExpansion) uses to observe newly-gossiped peers without becoming a second, competing consumer of this session's own single-reader events stream (each emitted SessionEvent wakes at most one waiter, so a second for-await loop over events would silently steal events from whichever consumer already reads it). Omit for a caller with no use for it, exactly today's behaviour. */
+onPeerAdvert?: (advert: PeerAdvert) => void,
+/** Fired once per frame received on this session's connection, with the Connection it arrived on: a new Connection after a reconnect is how a caller notices it has to announce itself again, and a core/data reply is how it receives a log it asked a hub for. Omit for a caller with no use for it, exactly today's behaviour. */
+onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>,
+/** Told of a failure that is local to this session and did not end it, while handling a hello from a peer: an identity port that failed to check or sign, an answering hello that could not be sent, a channel that could not be established. The hello is dropped, any half-made handshake for that peer is discarded, and the peer is told nothing, so no failure in handling a hello ends the session. Reports go through the shared fault reporter (fault-report.ts): at most one per peer per its interval, with the number withheld in between given as `suppressed` in the second argument, and at most its budget across all peers per interval, so a failure repeated for one peer is reported once and then counted. If the callback throws, or returns a promise that rejects, the reporter reports that to the console and swallows it. A report held back at the end of an interval is delivered when the interval ends, which can be after the session has closed. Omit for a caller with no use for it. */
+onLocalFault?: LocalFaultHandler): MeshSession;
+/** A MeshSession built over a connection that already exists (a Transport's own listen() handed it to onConnection), extended with the one thing a dial-side session can't offer: the device-id of the specific peer at the other end. Unlike createMeshSession, which may end up talking to a relay gossiping about many devices at once, an accepted connection is the agent-comms case -- exactly two peers, directly connected -- so "the peer" is well-defined here in a way it structurally isn't for the dial side. */
+interface AcceptedMeshSession extends MeshSession {
+  /** Resolves with the device-id carried by the first peer-advert this connection's remote sends -- the same self-advertisement mechanism createMeshSession's own directory already relies on for every peer, just narrowed to "the one peer this specific connection is with" rather than accumulated into a directory of possibly many. There is no transport-level authentication behind this yet (see wire-mesh#45's own createTlsTransport item): it is only as trustworthy as the remote's own gossip, exactly the same trust level the dial-side directory already has for every entry in it. */
+  peerDeviceId: Promise<DeviceId>;
+}
+interface AcceptedMeshSessionOptions {
+  /** A caller-chosen label for this connection, used only for ConnectionState's own address field -- the Connection/Transport ports expose no remote-address concept an accepted connection could report on its own (see wire-mesh#45). Defaults to a fixed placeholder since most callers have nothing more specific to offer; a transport adapter that does know the remote's address should pass it here. */
+  label?: string;
+  clock?: Readonly<Clock>;
+  /** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert. Omit (or pass none) for a caller with nothing to offer. */
+  addresses?: readonly string[];
+  /** Observes every frame this session receives, alongside (never instead of) its own manage-request/gossip/handshake handling (wire-mesh#102) -- the integration point an "ordinary opted-in node relays for peers it's already talking to" uses: pass a shared RelayHub instance's own handleFrame, bound to this connection, and it sees the identical frame stream this session's own applyFrame already consumes, with no second for-await loop racing over the same connection.receive(). A dedicated wire-mesh/cloudflare-hub deployment, which never runs a MeshSession at all, is unaffected -- this is additive, opt-in, and irrelevant to that case. */
+  onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>;
+  /** Fired once this session's own connection.receive() stream ends -- the counterpart a RelayHub's own forgetConnection needs, since its registry is keyed by this exact Connection and must be cleaned up when it specifically ends. */
+  onSessionEnd?: (connection: Readonly<Connection>) => void;
+  /** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- alongside (never instead of) this session's own internal peerDeviceId resolution, which uses this identical hook internally and keeps working unchanged. See createMeshSession's own onPeerAdvert doc comment for why this exists: a gossip-expansion consumer (wire-mesh#187) needs to observe every advert without becoming a second, competing consumer of this session's own single-reader events stream. */
+  onPeerAdvert?: (advert: PeerAdvert) => void;
+}
+/** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
+declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;
+//#endregion
+export { createMeshSession as _, DirectoryEntry as a, HANDSHAKE_TIMEOUT_MS as c, IncomingManageRequest as d, ManageOutcome as f, acceptMeshSession as g, SessionEvent as h, DataDomainFrame as i, HandshakeStatus as l, ReconnectPolicy as m, AcceptedMeshSessionOptions as n, FRAME_LOG_WINDOW as o, MeshSession as p, ConnectionState as r, FrameLogEntry as s, AcceptedMeshSession as t, IncomingDataFrame as u };

package/dist/mesh-session-DzcZYdhe.d.mts

@@ -0,0 +1,174 @@
+import { D as DeviceId, E as DataRequestFrame, N as Frame, T as DataHaveFrame, U as ManageError, V as ManageCommand, W as ManageOk, bt as RevocationEntry, et as PeerAdvert, f as CapabilityScope, g as CoordinatorFrame, lt as ProtocolVersion, nn as TopologyPeers, p as CapabilityToken, w as DataEntriesFrame } from "./protocol-Cb3BnuTL.mjs";
+import { r as Transport, t as Connection } from "./transport-CAD419ge.mjs";
+import { r as IdentityPort } from "./identity-CUr-jaAB.mjs";
+import { t as Clock } from "./clock-DhUPRfLh.mjs";
+//#region src/domain/local-fault.d.ts
+/** What `onFault` is told besides the error. */
+interface FaultContext {
+  /** The peer the failing hello or send was for, when it is known by then. */
+  readonly peer: DeviceId | undefined;
+  /** How many reports for this peer were withheld since the last one: the shared fault reporter makes at most one report per peer per interval and counts the rest. */
+  readonly suppressed: number;
+}
+/** What the owner of a session hears of failures local to this side: the error, and which peer it was for and how many reports for that peer were withheld. */
+type LocalFaultHandler = (error: unknown, context: FaultContext) => void | Promise<void>;
+//#endregion
+//#region src/domain/mesh-session.d.ts
+/** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
+declare const HANDSHAKE_TIMEOUT_MS = 3000;
+type ConnectionState = {
+  status: "idle";
+} | {
+  status: "connecting";
+  address: string;
+} | {
+  status: "connected";
+  address: string;
+  handshake: HandshakeStatus;
+} | {
+  status: "reconnecting";
+  address: string;
+  attempt: number;
+  reason: string;
+} | {
+  status: "closed";
+  address: string;
+  reason: string;
+};
+/** Opt-in retry behaviour for a session's own reconnect attempts. Left at its default `null` in createMeshSession, a disconnect always falls straight to `"closed"` -- today's exact behaviour, unchanged unless a caller opts in. */
+interface ReconnectPolicy {
+  maxAttempts: number;
+  /** Backoff before attempt N (1-indexed), in milliseconds. */
+  delayMs: (attempt: number) => number;
+}
+/** The union `manage-response-frame.outcome` actually carries -- no dedicated generated type name exists for it. */
+type ManageOutcome = ManageOk | ManageError;
+/** One `manage-request` this session received from its peer, surfaced for the caller to act on and answer. */
+interface IncomingManageRequest {
+  requestId: number;
+  command: ManageCommand;
+  scope: CapabilityScope;
+  token?: CapabilityToken;
+  /** The device-id of the peer this request was relayed on behalf of, as the end-to-end secure channel it arrived through authenticated it (spec/secure-channel.cddl): the identity that channel's handshake proved, never the `from-device` a hub stamps on relay-data, which a hub can set to anything. Present only when the request arrived through a relay pairing. A caller that needs to address a further request back to the same peer (one not sent via respond(), which already routes back correctly on its own) passes this as sendManageRequest's targetDevice. */
+  fromDevice?: DeviceId;
+  /** The device-id this request's relay-data frame was explicitly addressed to, read from its own `to-device` field -- present only when the request arrived relay-wrapped and the frame carried one. A caller fronting more than one locally-addressable device behind a single hub connection (a gateway advertising several local peers through the same relay pairing) uses this to decide whether the request is for this device or should be routed on to a different local peer it also advertises; this session has no such routing logic of its own, since it represents exactly one identity. */
+  toDevice?: DeviceId;
+  respond: (outcome: ManageOutcome) => Promise<void>;
+}
+/** The core/data frames: the raw have, request and entries primitive data-sync.ts answers. */
+type DataDomainFrame = DataHaveFrame | DataRequestFrame | DataEntriesFrame;
+/** One core/data frame this session received, surfaced for the application's replication policy to answer. */
+interface IncomingDataFrame {
+  frame: DataDomainFrame;
+  /** The device-id of the peer that sent this frame through a relay pairing, as the end-to-end secure channel it arrived through authenticated it (spec/secure-channel.cddl), never the `from-device` a hub stamps. Absent for a frame that arrived directly on the connection, whose sender is the connection's own peer. A reply goes back to this device through sendDataFrame's targetDevice. */
+  fromDevice?: DeviceId;
+  /** The device-id the frame's relay-data was addressed to, for a caller fronting several local devices behind one hub connection, exactly as IncomingManageRequest.toDevice. Present only for a relayed frame that carried one. */
+  toDevice?: DeviceId;
+}
+type HandshakeStatus = {
+  status: "pending";
+} | {
+  status: "negotiated";
+  version: ProtocolVersion;
+  sharedDomains: string[];
+} | {
+  status: "unanswered";
+} | {
+  status: "rejected";
+  reason: string;
+};
+interface SessionEvent {
+  state: ConnectionState;
+  /** The peer directory as of this event: latest peer-advert per device-id, in first-heard order. */
+  directory: readonly DirectoryEntry[];
+  /** The most recent frames that crossed the connection, sent or received, in order: at most FRAME_LOG_WINDOW entries, the recent-activity window a console shows rather than a session history. */
+  frameLog: readonly FrameLogEntry[];
+}
+interface DirectoryEntry {
+  device: DeviceId;
+  advert: PeerAdvert;
+}
+/**
+ * How many entries a session's frameLog keeps: the log exists for a console's
+ * recent-activity view, not as a session history, so it holds the most recent
+ * window of frames rather than every frame a long-lived session ever crossed.
+ * Without the bound, a busy session (a relay hub pairing, or any peer on a
+ * chatty mesh) retains every frame for its whole life, which on an
+ * always-on node grows without limit.
+ */
+declare const FRAME_LOG_WINDOW = 256;
+interface FrameLogEntry {
+  direction: "sent" | "received";
+  frame: Frame;
+}
+interface MeshSession {
+  readonly events: AsyncIterable<SessionEvent>;
+  /** Every `manage-request` received from the peer, in arrival order. */
+  readonly incomingManageRequests: AsyncIterable<IncomingManageRequest>;
+  /** Every core/data frame received, direct or through a relay pairing, in arrival order. A relayed one arrives only when it opened under the secure channel of the device that sent it, and names that device in `fromDevice`. What a frame means, and what to answer, is data-sync.ts's and the application's business, so the session only delivers it. */
+  readonly incomingDataFrames: AsyncIterable<IncomingDataFrame>;
+  /** Every `revocation-entry` received from the peer, in arrival order -- a `revocation-announce` frame's own `entries` array is flattened to one item per entry, since each entry is independently verifiable and independently meaningful regardless of which frame carried it. A consumer typically feeds each one into a RevocationView's own `record`. */
+  readonly revocationAnnouncements: AsyncIterable<RevocationEntry>;
+  /** Every `coordinator-frame` received from the peer, in arrival order: a gossiped, term-based claim to the rendezvous role (spec/transport.cddl), surfaced raw exactly like revocationAnnouncements because what a claim means is coordinator-election.ts's own business, not the session's. A consumer feeds each one into a CoordinatorElection's evaluate, and sends its own claims with sendCoordinatorClaim. */
+  readonly coordinatorFrames: AsyncIterable<CoordinatorFrame>;
+  connect: (address: string, localDomains: readonly string[]) => Promise<void>;
+  sendPing: () => Promise<void>;
+  /**
+   * Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives.
+   *
+   * The pairing is FIFO because ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's promise resolves against the Nth pong received after it, never matched by any other means.
+   *
+   * Rejects with a plain Error if the connection closes, and with a PingTimeoutError (from ping-round-trips.ts) when `timeoutMs` is given and no pong arrives within it, so a caller can tell an unanswered ping from a dropped connection. It never resolves a sentinel the way sendManageRequest's own timeout does, because there is no natural "no answer" value for a bare millisecond count to double as.
+   *
+   * Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong, which today means relay-hub's own frame handling (wire-mesh#181). Called against a plain peer that never sends pong it hangs until `timeoutMs` if given, or forever.
+   *
+   * It exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time it over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg.
+   */
+  sendPingMeasureRtt: (timeoutMs?: number) => Promise<number>;
+  /** Attaches this token to every `manage-request` sent from now on. */
+  setToken: (token: CapabilityToken) => void;
+  /** Announces one or more already-minted revocation-entries to the peer. Sent directly over the connection, never relay-wrapped -- revocation-announce is a gossiped broadcast, not a request addressed to a specific peer, so it has no targetDevice/token parameters the way sendManageRequest does. */
+  sendRevocationAnnounce: (entries: readonly RevocationEntry[]) => Promise<void>;
+  /** Sends one coordinator-frame directly over this session's own connection, never relay-wrapped: the claim is a gossiped broadcast like revocation-announce, not a request addressed to a specific peer. The frame itself comes from a CoordinatorElection (claim, or announceCurrent for a refresh), so the session never invents a term on its own. */
+  sendCoordinatorClaim: (frame: Readonly<CoordinatorFrame>) => Promise<void>;
+  /** Re-sends this side's own self-advert with a fresh snapshot-seconds and, when given, extensions merged onto peer-advert's own open `* tstr => any` tail -- the mechanism a caller uses to keep gossiped presence status (or any other advertised fact) live over a connection's lifetime, since the initial self-advert wireUpConnection sends at connect time is otherwise never repeated. Callers own their own re-advertisement cadence (there is no timer inside MeshSession itself, matching its own DOM-free, fully unit-testable design); a caller not calling this again after connecting is exactly today's existing gossip-once-on-connect behaviour. */
+  sendGossipUpdate: (extensions?: Record<string, unknown>) => Promise<void>;
+  /** This session's own current topology snapshot -- the identical `topology/peers` value buildSelfAdvert merges into every gossiped self-advert (wire-mesh#180), read back directly rather than only from a possibly-stale gossiped copy elsewhere in the mesh. The live, cache-bust half of the cached-vs-live split `topology.get` itself establishes: a caller answering an incoming topology.get manage-request (see topology.ts's createTopologyGetHandler) calls this to build the response. Synchronous and side-effect-free -- unlike every other method here, it sends nothing and works even before this session has ever connected (an unconnected session simply has no direct peer and no relay pairings yet, both honestly empty). */
+  getTopologyPeers: () => TopologyPeers;
+  /** Sends one core/data frame (data-have, data-request, or data-entries): the transport half of an application's own noticeboard replication policy (data-sync.ts owns what the frames MEAN; this owns getting one onto the wire), the same layering sendRevocationAnnounce already established for its own frame kind. Without targetDevice it goes directly over this session's own connection, never relay-wrapped, which is how a hub's mailbox is addressed. With targetDevice it is routed to that specific peer through a relay pairing, sealed on the secure channel with that device like a manage-request (spec/secure-channel.cddl), so two devices that reach each other only through a hub can run the data-domain exchange; the hub sees ciphertext and its mailbox is not involved. The peer's own frames come back through incomingDataFrames. Rejects when not connected, exactly like every other send method here. */
+  sendDataFrame: (frame: DataDomainFrame, targetDevice?: DeviceId) => Promise<void>;
+  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. When timeoutMs is given, the returned promise resolves with `{ result: "error", code: "timeout" }` rather than hanging forever if no manage-response arrives in time -- a held-open request (a human approval, a not-yet-online peer) otherwise has no way for the caller to give up on it. Absent, this request waits exactly as before, with no time limit of its own. */
+  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken, timeoutMs?: number) => Promise<ManageOutcome>;
+  close: () => Promise<void>;
+}
+declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null,
+/** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert so other peers can attempt a direct connection instead of always falling back to a relay. Omit (or pass none) for a caller with nothing to offer, e.g. a browser client. */
+addresses?: readonly string[],
+/** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- the hook a gossip-expansion consumer (wire-mesh#187, gossip-expansion.ts's own createGossipExpansion) uses to observe newly-gossiped peers without becoming a second, competing consumer of this session's own single-reader events stream (each emitted SessionEvent wakes at most one waiter, so a second for-await loop over events would silently steal events from whichever consumer already reads it). Omit for a caller with no use for it, exactly today's behaviour. */
+onPeerAdvert?: (advert: PeerAdvert) => void,
+/** Fired once per frame received on this session's connection, with the Connection it arrived on: a new Connection after a reconnect is how a caller notices it has to announce itself again, and a core/data reply is how it receives a log it asked a hub for. Omit for a caller with no use for it, exactly today's behaviour. */
+onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>,
+/** Told of a failure that is local to this session and did not end it, while handling a hello from a peer: an identity port that failed to check or sign, an answering hello that could not be sent, a channel that could not be established. The hello is dropped, any half-made handshake for that peer is discarded, and the peer is told nothing, so no failure in handling a hello ends the session. Reports go through the shared fault reporter (fault-report.ts): at most one per peer per its interval, with the number withheld in between given as `suppressed` in the second argument, and at most its budget across all peers per interval, so a failure repeated for one peer is reported once and then counted. If the callback throws, or returns a promise that rejects, the reporter reports that to the console and swallows it. A report held back at the end of an interval is delivered when the interval ends, which can be after the session has closed. Omit for a caller with no use for it. */
+onLocalFault?: LocalFaultHandler): MeshSession;
+/** A MeshSession built over a connection that already exists (a Transport's own listen() handed it to onConnection), extended with the one thing a dial-side session can't offer: the device-id of the specific peer at the other end. Unlike createMeshSession, which may end up talking to a relay gossiping about many devices at once, an accepted connection is the agent-comms case -- exactly two peers, directly connected -- so "the peer" is well-defined here in a way it structurally isn't for the dial side. */
+interface AcceptedMeshSession extends MeshSession {
+  /** Resolves with the device-id carried by the first peer-advert this connection's remote sends -- the same self-advertisement mechanism createMeshSession's own directory already relies on for every peer, just narrowed to "the one peer this specific connection is with" rather than accumulated into a directory of possibly many. There is no transport-level authentication behind this yet (see wire-mesh#45's own createTlsTransport item): it is only as trustworthy as the remote's own gossip, exactly the same trust level the dial-side directory already has for every entry in it. */
+  peerDeviceId: Promise<DeviceId>;
+}
+interface AcceptedMeshSessionOptions {
+  /** A caller-chosen label for this connection, used only for ConnectionState's own address field -- the Connection/Transport ports expose no remote-address concept an accepted connection could report on its own (see wire-mesh#45). Defaults to a fixed placeholder since most callers have nothing more specific to offer; a transport adapter that does know the remote's address should pass it here. */
+  label?: string;
+  clock?: Readonly<Clock>;
+  /** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert. Omit (or pass none) for a caller with nothing to offer. */
+  addresses?: readonly string[];
+  /** Observes every frame this session receives, alongside (never instead of) its own manage-request/gossip/handshake handling (wire-mesh#102) -- the integration point an "ordinary opted-in node relays for peers it's already talking to" uses: pass a shared RelayHub instance's own handleFrame, bound to this connection, and it sees the identical frame stream this session's own applyFrame already consumes, with no second for-await loop racing over the same connection.receive(). A dedicated wire-mesh/cloudflare-hub deployment, which never runs a MeshSession at all, is unaffected -- this is additive, opt-in, and irrelevant to that case. */
+  onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>;
+  /** Fired once this session's own connection.receive() stream ends -- the counterpart a RelayHub's own forgetConnection needs, since its registry is keyed by this exact Connection and must be cleaned up when it specifically ends. */
+  onSessionEnd?: (connection: Readonly<Connection>) => void;
+  /** Fired for every peer-advert entry as it's applied to the directory, regardless of source -- alongside (never instead of) this session's own internal peerDeviceId resolution, which uses this identical hook internally and keeps working unchanged. See createMeshSession's own onPeerAdvert doc comment for why this exists: a gossip-expansion consumer (wire-mesh#187) needs to observe every advert without becoming a second, competing consumer of this session's own single-reader events stream. */
+  onPeerAdvert?: (advert: PeerAdvert) => void;
+}
+/** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
+declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;
+//#endregion
+export { createMeshSession as _, DirectoryEntry as a, HANDSHAKE_TIMEOUT_MS as c, IncomingManageRequest as d, ManageOutcome as f, acceptMeshSession as g, SessionEvent as h, DataDomainFrame as i, HandshakeStatus as l, ReconnectPolicy as m, AcceptedMeshSessionOptions as n, FRAME_LOG_WINDOW as o, MeshSession as p, ConnectionState as r, FrameLogEntry as s, AcceptedMeshSession as t, IncomingDataFrame as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "dependencies": {
     "cbor2": "2.3.0",
     "cddl.js": "2.0.0",
@@ -23,7 +23,8 @@
     "tsdown": "0.23.0",
     "turbo": "2.10.12",
     "typescript": "6.0.3",
-    "vitest": "5.0.0"
+    "vitest": "5.0.0",
+    "wire-mesh-core-released": "npm:wire-mesh-core@4.1.5"
   },
   "exports": {
     "./adapters/byte-stream-connection": {