wire-mesh-core 1.53.0 → 1.55.0

package/dist/adapters/frame-codec.d.cts

@@ -1,4 +1,4 @@
-import { D as DeviceId, N as Frame, ft as RelayDataFrame } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId, N as Frame, ht as RelayDataFrame } from "../protocol-PhUVprXA.cjs";
 //#region src/adapters/frame-codec.d.ts
 export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
 /** Wraps frame as a relay-data-frame's own opaque payload, stamping to-device when the caller knows which established pairing to address it to (wire-mesh#30) -- the outbound counterpart to tryDecodeFrame's own doc comment below, which describes the inbound side of the same relay-data envelope. Omitting toDevice leaves the frame unaddressed, which the receiving hub then routes via its own most-recently-established-pairing fallback. */

package/dist/adapters/frame-codec.d.mts

@@ -1,4 +1,4 @@
-import { D as DeviceId, N as Frame, ft as RelayDataFrame } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId, N as Frame, ht as RelayDataFrame } from "../protocol-PhUVprXA.mjs";
 //#region src/adapters/frame-codec.d.ts
 export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
 /** Wraps frame as a relay-data-frame's own opaque payload, stamping to-device when the caller knows which established pairing to address it to (wire-mesh#30) -- the outbound counterpart to tryDecodeFrame's own doc comment below, which describes the inbound side of the same relay-data envelope. Omitting toDevice leaves the frame unaddressed, which the receiving hub then routes via its own most-recently-established-pairing fallback. */

package/dist/adapters/node-identity.d.cts

@@ -1,5 +1,5 @@
-import { B as IdentityKey, D as DeviceId } from "../protocol-CNFRVx9w.cjs";
-import { t as IdentityPort } from "../identity-CUkDHCRK.cjs";
+import { B as IdentityKey, D as DeviceId } from "../protocol-PhUVprXA.cjs";
+import { t as IdentityPort } from "../identity-CmD4l_Mp.cjs";
 import { webcrypto } from "node:crypto";
 //#region src/adapters/node-identity.d.ts
 export declare function deriveDeviceId(publicKey: Uint8Array): Promise<DeviceId>;

package/dist/adapters/node-identity.d.mts

@@ -1,5 +1,5 @@
-import { B as IdentityKey, D as DeviceId } from "../protocol-CNFRVx9w.mjs";
-import { t as IdentityPort } from "../identity-9TmmK7vP.mjs";
+import { B as IdentityKey, D as DeviceId } from "../protocol-PhUVprXA.mjs";
+import { t as IdentityPort } from "../identity-BXrJ6_YM.mjs";
 import { webcrypto } from "node:crypto";
 //#region src/adapters/node-identity.d.ts
 export declare function deriveDeviceId(publicKey: Uint8Array): Promise<DeviceId>;

package/dist/adapters/tcp-transport.d.cts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-De0zHlaA.cjs";
+import { r as Transport } from "../transport-CbXX1Xd-.cjs";
 //#region src/adapters/tcp-transport.d.ts
 /** A Node net.Socket-based Transport: length-prefixed, CBOR-encoded frames over plain TCP -- matching Cascade's own transport shape, since interop with Cascade nodes is wire-mesh's stated goal. Framing (not TLS) is this adapter's own concern; a TLS-terminated variant is a separate adapter behind the same Transport contract. */
 export declare function createTcpTransport(): Transport;

package/dist/adapters/tcp-transport.d.mts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-C7KVkhgb.mjs";
+import { r as Transport } from "../transport-DG9ouGe-.mjs";
 //#region src/adapters/tcp-transport.d.ts
 /** A Node net.Socket-based Transport: length-prefixed, CBOR-encoded frames over plain TCP -- matching Cascade's own transport shape, since interop with Cascade nodes is wire-mesh's stated goal. Framing (not TLS) is this adapter's own concern; a TLS-terminated variant is a separate adapter behind the same Transport contract. */
 export declare function createTcpTransport(): Transport;

package/dist/adapters/threshold-identity.d.cts

@@ -1,5 +1,5 @@
-import { D as DeviceId } from "../protocol-CNFRVx9w.cjs";
-import { t as IdentityPort } from "../identity-CUkDHCRK.cjs";
+import { D as DeviceId } from "../protocol-PhUVprXA.cjs";
+import { t as IdentityPort } from "../identity-CmD4l_Mp.cjs";
 import { DeviceKeyed } from "./threshold-wasm.cjs";
 import { ThresholdSubject } from "../domain/threshold-subject.cjs";
 //#region src/adapters/threshold-identity.d.ts

package/dist/adapters/threshold-identity.d.mts

@@ -1,5 +1,5 @@
-import { D as DeviceId } from "../protocol-CNFRVx9w.mjs";
-import { t as IdentityPort } from "../identity-9TmmK7vP.mjs";
+import { D as DeviceId } from "../protocol-PhUVprXA.mjs";
+import { t as IdentityPort } from "../identity-BXrJ6_YM.mjs";
 import { DeviceKeyed } from "./threshold-wasm.mjs";
 import { ThresholdSubject } from "../domain/threshold-subject.mjs";
 //#region src/adapters/threshold-identity.d.ts

package/dist/adapters/threshold-wasm.d.cts

@@ -1,4 +1,4 @@
-import { D as DeviceId } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId } from "../protocol-PhUVprXA.cjs";
 //#region src/adapters/threshold-wasm.d.ts
 /** One `(deviceId, bytes)` pair -- the wasm boundary's own encoding of a map keyed by participant, since wasm-bindgen has no built-in `Map<Uint8Array, Uint8Array>` marshalling. */
 export interface DeviceKeyed<T extends Uint8Array = Uint8Array<ArrayBuffer>> {

package/dist/adapters/threshold-wasm.d.mts

@@ -1,4 +1,4 @@
-import { D as DeviceId } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId } from "../protocol-PhUVprXA.mjs";
 //#region src/adapters/threshold-wasm.d.ts
 /** One `(deviceId, bytes)` pair -- the wasm boundary's own encoding of a map keyed by participant, since wasm-bindgen has no built-in `Map<Uint8Array, Uint8Array>` marshalling. */
 export interface DeviceKeyed<T extends Uint8Array = Uint8Array<ArrayBuffer>> {

package/dist/adapters/tls-transport.d.cts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-De0zHlaA.cjs";
+import { r as Transport } from "../transport-CbXX1Xd-.cjs";
 //#region src/adapters/tls-transport.d.ts
 export interface TlsIdentity {
   certificatePem: string;

package/dist/adapters/tls-transport.d.mts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-C7KVkhgb.mjs";
+import { r as Transport } from "../transport-DG9ouGe-.mjs";
 //#region src/adapters/tls-transport.d.ts
 export interface TlsIdentity {
   certificatePem: string;

package/dist/domain/bulk.d.cts

@@ -1,6 +1,6 @@
-import { D as DeviceId, N as Frame, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId, N as Frame, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-PhUVprXA.cjs";
 import { KeyValueStorage } from "../ports/storage.cjs";
-import { t as Connection } from "../transport-De0zHlaA.cjs";
+import { t as Connection } from "../transport-CbXX1Xd-.cjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.cjs";
 //#region src/domain/bulk.d.ts
 /** The two capabilities matching the direction each manage-command actually flows (spec/bulk.cddl): the sender proves write authority to open a transfer, the receiver proves read authority to ask for one to continue. */

package/dist/domain/bulk.d.mts

@@ -1,6 +1,6 @@
-import { D as DeviceId, N as Frame, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId, N as Frame, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-PhUVprXA.mjs";
 import { KeyValueStorage } from "../ports/storage.mjs";
-import { t as Connection } from "../transport-C7KVkhgb.mjs";
+import { t as Connection } from "../transport-DG9ouGe-.mjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.mjs";
 //#region src/domain/bulk.d.ts
 /** The two capabilities matching the direction each manage-command actually flows (spec/bulk.cddl): the sender proves write authority to open a transfer, the receiver proves read authority to ask for one to continue. */

package/dist/domain/capability-grant.d.cts

@@ -1,8 +1,8 @@
-import { D as DeviceId, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-CNFRVx9w.cjs";
-import { t as IdentityPort } from "../identity-CUkDHCRK.cjs";
+import { D as DeviceId, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-PhUVprXA.cjs";
+import { t as IdentityPort } from "../identity-CmD4l_Mp.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
 import { IncomingManageRequest, ManageOutcome, MeshSession } from "./mesh-session.cjs";
-import { a as RevocationCheck } from "../tokens-Cl8sQo7o.cjs";
+import { a as RevocationCheck } from "../tokens-DIPzZ9JJ.cjs";
 //#region src/domain/capability-grant.d.ts
 /**
  * Builds a capability-grant command per management.cddl. The outer `manage-command.verb` is the capability string itself, the identical convention capability-request.ts's own buildCapabilityRequestCommand already establishes -- a receiver's per-capability handler is how it knows which grant this push is even for. `params.verb` is the fixed "capability.grant" marker. No scope or invitee field: manage-request-frame's own top-level scope already carries the former, and the request's own destination already carries the latter -- naming either a second time inside params could only ever disagree with the fact it duplicates.

package/dist/domain/capability-grant.d.mts

@@ -1,8 +1,8 @@
-import { D as DeviceId, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-CNFRVx9w.mjs";
-import { t as IdentityPort } from "../identity-9TmmK7vP.mjs";
+import { D as DeviceId, V as ManageCommand, f as CapabilityScope, p as CapabilityToken } from "../protocol-PhUVprXA.mjs";
+import { t as IdentityPort } from "../identity-BXrJ6_YM.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
 import { IncomingManageRequest, ManageOutcome, MeshSession } from "./mesh-session.mjs";
-import { a as RevocationCheck } from "../tokens-CVyPoJ6l.mjs";
+import { a as RevocationCheck } from "../tokens-BVrgBeqF.mjs";
 //#region src/domain/capability-grant.d.ts
 /**
  * Builds a capability-grant command per management.cddl. The outer `manage-command.verb` is the capability string itself, the identical convention capability-request.ts's own buildCapabilityRequestCommand already establishes -- a receiver's per-capability handler is how it knows which grant this push is even for. `params.verb` is the fixed "capability.grant" marker. No scope or invitee field: manage-request-frame's own top-level scope already carries the former, and the request's own destination already carries the latter -- naming either a second time inside params could only ever disagree with the fact it duplicates.

package/dist/domain/capability-request.d.cts

@@ -1,5 +1,5 @@
-import { D as DeviceId, V as ManageCommand, f as CapabilityScope, u as CapabilityGrantOk } from "../protocol-CNFRVx9w.cjs";
-import { t as IdentityPort } from "../identity-CUkDHCRK.cjs";
+import { D as DeviceId, V as ManageCommand, f as CapabilityScope, u as CapabilityGrantOk } from "../protocol-PhUVprXA.cjs";
+import { t as IdentityPort } from "../identity-CmD4l_Mp.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.cjs";
 //#region src/domain/capability-request.d.ts

package/dist/domain/capability-request.d.mts

@@ -1,5 +1,5 @@
-import { D as DeviceId, V as ManageCommand, f as CapabilityScope, u as CapabilityGrantOk } from "../protocol-CNFRVx9w.mjs";
-import { t as IdentityPort } from "../identity-9TmmK7vP.mjs";
+import { D as DeviceId, V as ManageCommand, f as CapabilityScope, u as CapabilityGrantOk } from "../protocol-PhUVprXA.mjs";
+import { t as IdentityPort } from "../identity-BXrJ6_YM.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.mjs";
 //#region src/domain/capability-request.d.ts

package/dist/domain/data-sync.d.cts

@@ -1,6 +1,6 @@
-import { D as DeviceId, E as DataRequestFrame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId, E as DataRequestFrame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-PhUVprXA.cjs";
 import { KeyValueStorage } from "../ports/storage.cjs";
-import { t as IdentityPort } from "../identity-CUkDHCRK.cjs";
+import { t as IdentityPort } from "../identity-CmD4l_Mp.cjs";
 //#region src/domain/data-sync.d.ts
 export interface DataSyncOptions {
   identity: IdentityPort;

package/dist/domain/data-sync.d.mts

@@ -1,6 +1,6 @@
-import { D as DeviceId, E as DataRequestFrame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId, E as DataRequestFrame, T as DataHaveFrame, w as DataEntriesFrame } from "../protocol-PhUVprXA.mjs";
 import { KeyValueStorage } from "../ports/storage.mjs";
-import { t as IdentityPort } from "../identity-9TmmK7vP.mjs";
+import { t as IdentityPort } from "../identity-BXrJ6_YM.mjs";
 //#region src/domain/data-sync.d.ts
 export interface DataSyncOptions {
   identity: IdentityPort;

package/dist/domain/device-id.d.cts

@@ -1,4 +1,4 @@
-import { D as DeviceId } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId } from "../protocol-PhUVprXA.cjs";
 //#region src/domain/device-id.d.ts
 /** Lowercase, byte-exact hex for an arbitrary-length byte string -- the same encoding convention deviceIdToHex uses for the fixed-length device-id case, extracted so any other byte string needing a stable, displayable, map-keyable text form (e.g. a token-id, which tokens.cddl defines as an arbitrary-length bstr rather than a 32-byte device-id) can use the identical convention without going through a device-id-shaped function. */
 export declare function bytesToHex(bytes: Uint8Array): string;

package/dist/domain/device-id.d.mts

@@ -1,4 +1,4 @@
-import { D as DeviceId } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId } from "../protocol-PhUVprXA.mjs";
 //#region src/domain/device-id.d.ts
 /** Lowercase, byte-exact hex for an arbitrary-length byte string -- the same encoding convention deviceIdToHex uses for the fixed-length device-id case, extracted so any other byte string needing a stable, displayable, map-keyable text form (e.g. a token-id, which tokens.cddl defines as an arbitrary-length bstr rather than a 32-byte device-id) can use the identical convention without going through a device-id-shaped function. */
 export declare function bytesToHex(bytes: Uint8Array): string;

package/dist/domain/gossip-expansion.cjs

@@ -0,0 +1,44 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_device_id = require("./device-id.cjs");
+//#region src/domain/gossip-expansion.ts
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+function createGossipExpansion(options) {
+	const selfHex = require_domain_device_id.deviceIdToHex(options.selfDeviceId);
+	const considered = /* @__PURE__ */ new Set();
+	async function expand(candidate) {
+		let approved;
+		try {
+			approved = await options.shouldExpand(candidate);
+		} catch (error) {
+			options.onExpansionFailed?.(candidate, [toError(error)]);
+			return;
+		}
+		if (!approved) {
+			options.onExpansionDeclined?.(candidate);
+			return;
+		}
+		const errors = [];
+		for (const address of candidate.addresses) try {
+			const session = await options.dial(address);
+			options.onExpanded(candidate, address, session);
+			return;
+		} catch (error) {
+			errors.push(toError(error));
+		}
+		options.onExpansionFailed?.(candidate, errors);
+	}
+	return { considerAdvert(advert) {
+		const hex = require_domain_device_id.deviceIdToHex(advert.device);
+		if (hex === selfHex || considered.has(hex) || advert.addresses.length === 0) return;
+		considered.add(hex);
+		expand({
+			device: advert.device,
+			addresses: advert.addresses
+		});
+	} };
+}
+//#endregion
+exports.createGossipExpansion = createGossipExpansion;

package/dist/domain/gossip-expansion.d.cts

@@ -0,0 +1,29 @@
+import { D as DeviceId, et as PeerAdvert } from "../protocol-PhUVprXA.cjs";
+import { MeshSession } from "./mesh-session.cjs";
+//#region src/domain/gossip-expansion.d.ts
+/** One not-yet-considered device this session's gossip directory has surfaced, carrying only what a dial/trust decision needs: the device-id to decide identity, and the "host:port" addresses its own peer-advert claims are directly reachable at, in the order it advertised them. */
+export interface GossipExpansionCandidate {
+  readonly device: DeviceId;
+  readonly addresses: readonly string[];
+}
+export interface GossipExpansionOptions {
+  /** This session's own device-id, so its own self-advert (looped back through gossip forwarding or a hub's catch-up frame) is never offered to shouldExpand as if it were a distinct peer. */
+  selfDeviceId: DeviceId;
+  /** Decides whether to attempt a direct connection to a newly-discovered device at all -- called at most once per device for this GossipExpansion instance's lifetime, never re-asked if the same device later re-adverts (an address change, a fresher snapshot-seconds). Returning true does not guarantee a connection: dial may still fail for every one of the candidate's addresses, reported via onExpansionFailed. */
+  shouldExpand: (candidate: Readonly<GossipExpansionCandidate>) => Promise<boolean> | boolean;
+  /** Attempts one direct connection to `address`, resolving with a fully connected MeshSession or rejecting if the dial/handshake fails. Typically wraps createMeshSession(transport, identity, ...) followed by session.connect(address, localDomains). Called once per address of an approved candidate, in the order it advertised them, stopping at the first that succeeds -- the caller owns cleanup of any partially-established session behind a rejected dial, since this module never holds a reference to one that didn't resolve. */
+  dial: (address: string) => Promise<MeshSession>;
+  /** Called once a candidate's dial succeeds, with the specific address that connected (one of candidate.addresses, not necessarily the first -- earlier ones may have failed) and the now-connected session, so the caller can wire it into whatever it already does for its own sessions (render it, merge its directory, route messages). */
+  onExpanded: (candidate: Readonly<GossipExpansionCandidate>, address: string, session: MeshSession) => void;
+  /** Called when shouldExpand itself declines a candidate. */
+  onExpansionDeclined?: (candidate: Readonly<GossipExpansionCandidate>) => void;
+  /** Called once every one of an approved candidate's addresses has failed to connect, or shouldExpand itself rejected -- in the latter case, errors holds exactly the one rejection reason, so a caller doesn't need two separate failure channels to observe every way expansion can fail short of success. */
+  onExpansionFailed?: (candidate: Readonly<GossipExpansionCandidate>, errors: readonly Error[]) => void;
+}
+export interface GossipExpansion {
+  /** Feed one just-received peer-advert -- from the session whose peer-adverts this expansion watches, via its own onPeerAdvert hook -- to decide whether it names a newly-discoverable peer worth expanding to, and if so kick off an expansion attempt for it. Never awaits a dial to completion inline: expansion happens in the background, observable only through onExpanded/onExpansionDeclined/onExpansionFailed. */
+  considerAdvert: (advert: Readonly<PeerAdvert>) => void;
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+export declare function createGossipExpansion(options: Readonly<GossipExpansionOptions>): GossipExpansion;
+//#endregion

package/dist/domain/gossip-expansion.d.mts

@@ -0,0 +1,29 @@
+import { D as DeviceId, et as PeerAdvert } from "../protocol-PhUVprXA.mjs";
+import { MeshSession } from "./mesh-session.mjs";
+//#region src/domain/gossip-expansion.d.ts
+/** One not-yet-considered device this session's gossip directory has surfaced, carrying only what a dial/trust decision needs: the device-id to decide identity, and the "host:port" addresses its own peer-advert claims are directly reachable at, in the order it advertised them. */
+export interface GossipExpansionCandidate {
+  readonly device: DeviceId;
+  readonly addresses: readonly string[];
+}
+export interface GossipExpansionOptions {
+  /** This session's own device-id, so its own self-advert (looped back through gossip forwarding or a hub's catch-up frame) is never offered to shouldExpand as if it were a distinct peer. */
+  selfDeviceId: DeviceId;
+  /** Decides whether to attempt a direct connection to a newly-discovered device at all -- called at most once per device for this GossipExpansion instance's lifetime, never re-asked if the same device later re-adverts (an address change, a fresher snapshot-seconds). Returning true does not guarantee a connection: dial may still fail for every one of the candidate's addresses, reported via onExpansionFailed. */
+  shouldExpand: (candidate: Readonly<GossipExpansionCandidate>) => Promise<boolean> | boolean;
+  /** Attempts one direct connection to `address`, resolving with a fully connected MeshSession or rejecting if the dial/handshake fails. Typically wraps createMeshSession(transport, identity, ...) followed by session.connect(address, localDomains). Called once per address of an approved candidate, in the order it advertised them, stopping at the first that succeeds -- the caller owns cleanup of any partially-established session behind a rejected dial, since this module never holds a reference to one that didn't resolve. */
+  dial: (address: string) => Promise<MeshSession>;
+  /** Called once a candidate's dial succeeds, with the specific address that connected (one of candidate.addresses, not necessarily the first -- earlier ones may have failed) and the now-connected session, so the caller can wire it into whatever it already does for its own sessions (render it, merge its directory, route messages). */
+  onExpanded: (candidate: Readonly<GossipExpansionCandidate>, address: string, session: MeshSession) => void;
+  /** Called when shouldExpand itself declines a candidate. */
+  onExpansionDeclined?: (candidate: Readonly<GossipExpansionCandidate>) => void;
+  /** Called once every one of an approved candidate's addresses has failed to connect, or shouldExpand itself rejected -- in the latter case, errors holds exactly the one rejection reason, so a caller doesn't need two separate failure channels to observe every way expansion can fail short of success. */
+  onExpansionFailed?: (candidate: Readonly<GossipExpansionCandidate>, errors: readonly Error[]) => void;
+}
+export interface GossipExpansion {
+  /** Feed one just-received peer-advert -- from the session whose peer-adverts this expansion watches, via its own onPeerAdvert hook -- to decide whether it names a newly-discoverable peer worth expanding to, and if so kick off an expansion attempt for it. Never awaits a dial to completion inline: expansion happens in the background, observable only through onExpanded/onExpansionDeclined/onExpansionFailed. */
+  considerAdvert: (advert: Readonly<PeerAdvert>) => void;
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+export declare function createGossipExpansion(options: Readonly<GossipExpansionOptions>): GossipExpansion;
+//#endregion

package/dist/domain/gossip-expansion.mjs

@@ -0,0 +1,43 @@
+import { deviceIdToHex } from "./device-id.mjs";
+//#region src/domain/gossip-expansion.ts
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/** Builds the per-device expansion state machine: ask once, dial every advertised address in order on approval, report exactly one outcome. */
+function createGossipExpansion(options) {
+	const selfHex = deviceIdToHex(options.selfDeviceId);
+	const considered = /* @__PURE__ */ new Set();
+	async function expand(candidate) {
+		let approved;
+		try {
+			approved = await options.shouldExpand(candidate);
+		} catch (error) {
+			options.onExpansionFailed?.(candidate, [toError(error)]);
+			return;
+		}
+		if (!approved) {
+			options.onExpansionDeclined?.(candidate);
+			return;
+		}
+		const errors = [];
+		for (const address of candidate.addresses) try {
+			const session = await options.dial(address);
+			options.onExpanded(candidate, address, session);
+			return;
+		} catch (error) {
+			errors.push(toError(error));
+		}
+		options.onExpansionFailed?.(candidate, errors);
+	}
+	return { considerAdvert(advert) {
+		const hex = deviceIdToHex(advert.device);
+		if (hex === selfHex || considered.has(hex) || advert.addresses.length === 0) return;
+		considered.add(hex);
+		expand({
+			device: advert.device,
+			addresses: advert.addresses
+		});
+	} };
+}
+//#endregion
+export { createGossipExpansion };

package/dist/domain/grant-candidates.d.cts

@@ -1,4 +1,4 @@
-import { D as DeviceId, f as CapabilityScope } from "../protocol-CNFRVx9w.cjs";
+import { D as DeviceId, f as CapabilityScope } from "../protocol-PhUVprXA.cjs";
 import { DirectoryEntry, MeshSession } from "./mesh-session.cjs";
 import { z } from "zod";
 //#region src/domain/grant-candidates.d.ts

package/dist/domain/grant-candidates.d.mts

@@ -1,4 +1,4 @@
-import { D as DeviceId, f as CapabilityScope } from "../protocol-CNFRVx9w.mjs";
+import { D as DeviceId, f as CapabilityScope } from "../protocol-PhUVprXA.mjs";
 import { DirectoryEntry, MeshSession } from "./mesh-session.mjs";
 import { z } from "zod";
 //#region src/domain/grant-candidates.d.ts

package/dist/domain/handshake.d.cts

@@ -1,4 +1,4 @@
-import { A as DomainId, R as HandshakeFrame, ot as ProtocolVersion } from "../protocol-CNFRVx9w.cjs";
+import { A as DomainId, R as HandshakeFrame, lt as ProtocolVersion } from "../protocol-PhUVprXA.cjs";
 //#region src/domain/handshake.d.ts
 /** The highest protocol version this build of core understands. */
 export declare const SUPPORTED_PROTOCOL_VERSION: ProtocolVersion;

package/dist/domain/handshake.d.mts

@@ -1,4 +1,4 @@
-import { A as DomainId, R as HandshakeFrame, ot as ProtocolVersion } from "../protocol-CNFRVx9w.mjs";
+import { A as DomainId, R as HandshakeFrame, lt as ProtocolVersion } from "../protocol-PhUVprXA.mjs";
 //#region src/domain/handshake.d.ts
 /** The highest protocol version this build of core understands. */
 export declare const SUPPORTED_PROTOCOL_VERSION: ProtocolVersion;

package/dist/domain/mesh-session.cjs

@@ -13,8 +13,43 @@ function createRelayPairings() {
 	};
 }
 //#endregion
-//#region src/domain/mesh-session.ts
-const MS_PER_SECOND = 1e3;
+//#region src/domain/ping-round-trips.ts
+function createPingRoundTrips() {
+	const pending = [];
+	function cancel(sentAt) {
+		const index = pending.findIndex((entry) => entry.sentAt === sentAt);
+		if (index === -1) return false;
+		pending.splice(index, 1);
+		return true;
+	}
+	return {
+		resolveOldest(nowMs) {
+			const entry = pending.shift();
+			if (entry !== void 0) entry.resolve(nowMs - entry.sentAt);
+		},
+		rejectAll(reason) {
+			for (const entry of pending.splice(0)) entry.reject(new Error(reason));
+		},
+		async sendAndAwait(sentAt, sendPing, timeoutMs) {
+			const rtt = new Promise((resolve, reject) => {
+				pending.push({
+					sentAt,
+					resolve,
+					reject
+				});
+			});
+			await sendPing();
+			if (timeoutMs === void 0) return rtt;
+			return Promise.race([rtt, new Promise((_resolve, reject) => {
+				setTimeout(() => {
+					if (cancel(sentAt)) reject(/* @__PURE__ */ new Error("timed out waiting for pong"));
+				}, timeoutMs);
+			})]);
+		}
+	};
+}
+//#endregion
+//#region src/domain/gossip-extensions.ts
 /** peer-advert's own three typed fields -- reserved so a `sendGossipUpdate` caller can never override the session's own device-id, address list, or freshness timestamp by supplying an extension of the same name. */
 const RESERVED_PEER_ADVERT_KEYS = /* @__PURE__ */ new Set([
 	"device",
@@ -30,6 +65,9 @@ function validateGossipExtensions(extensions) {
 		if (!GOSSIP_EXTENSION_KEY_PATTERN.test(key)) throw new Error(`sendGossipUpdate extension key "${key}" must be domain-qualified as "<domain>/<field>" (e.g. "presence/status")`);
 	}
 }
+//#endregion
+//#region src/domain/mesh-session.ts
+const MS_PER_SECOND = 1e3;
 /** 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. */
 const HANDSHAKE_TIMEOUT_MS = 3e3;
 function localHandshake(domains) {
@@ -62,6 +100,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	const incomingBacklog = [];
 	const revocationWaiters = [];
 	const revocationBacklog = [];
+	const pingRoundTrips = createPingRoundTrips();
 	function snapshot() {
 		return {
 			state,
@@ -101,6 +140,11 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			...token !== null ? { token } : {}
 		};
 	}
+	/** The "not connected" guard every send* method on the public session needs, deduplicated into one place rather than repeated inline at each call site: throws unless there is a live connection AND the session's own state machine agrees it is "connected" (transmit's own connection===null check alone doesn't cover the latter). Returns the connection itself, narrowed non-null, for a caller that needs to send directly on it (sendPing/sendPingMeasureRtt); a caller that only needs the throwing side effect (sendManageRequest and friends, which go through transmit instead) calls this and discards the result. */
+	function requireConnectedLink() {
+		if (connection === null || state.status !== "connected") throw new Error("not connected");
+		return connection;
+	}
 	/** Sends a frame, wrapping it as relay-data first when viaRelay is set -- the single choke point every outbound manage-request/manage-response passes through, so a consumer of sendManageRequest/respond never needs its own relay-wrapping logic. When relaying, toDevice is stamped onto the outer relay-data-frame's own `to-device` field so the hub addresses it to the correct pairing directly (wire-mesh#30) rather than falling back to whichever pairing it last saw -- the one case this is omitted is a response to a request that itself arrived with no from-device to echo back, which is left to that same hub fallback exactly as an unaddressed relay-data always has been. */
 	async function transmit(frame, viaRelay, toDevice) {
 		if (connection === null) throw new Error("not connected");
@@ -178,6 +222,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		else if (frame.type === "relay-inbound") relayPairings.add(frame["source-device"]);
 		else if (frame.type === "manage-response") applyManageResponse(frame);
 		else if (frame.type === "manage-request") applyManageRequest(frame);
+		else if (frame.type === "pong") pingRoundTrips.resolveOldest(clock.now());
 		else if (frame.type === "revocation-announce") for (const entry of frame.entries) emitRevocationEntry(entry);
 	}
 	/** Establishes a relay-connect pairing to targetDevice if this session isn't already paired with it -- a no-op when it already is, whether that pairing was established by this session's own prior relay-connect (initiator role) or learned from an incoming relay-inbound (target role, replying back to whoever dialed it). Pairing with a new target never tears down an existing pairing with a different one: this connection can hold several simultaneously (wire-mesh#30's own multiplexed adjacency map), so a later request back to an already-paired target must not re-send relay-connect for it. relay-connect has no ack frame: the initiator proceeds to relay-data right after sending it. */
@@ -220,6 +265,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	function handleDisconnect(reason, address, localDomains) {
 		if (feedCancelled) return;
 		rejectPendingManageRequests("disconnected before a response arrived");
+		pingRoundTrips.rejectAll("disconnected before a pong arrived");
 		if (reconnect !== null && attempt < reconnect.maxAttempts) {
 			attempt += 1;
 			const currentAttempt = attempt;
@@ -378,20 +424,32 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				await doConnect(address, localDomains);
 			},
 			async sendPing() {
-				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				const link = requireConnectedLink();
 				const ping = { type: "ping" };
 				frameLog.push({
 					direction: "sent",
 					frame: ping
 				});
-				await connection.send(ping);
+				await link.send(ping);
 				emit();
 			},
+			async sendPingMeasureRtt(timeoutMs) {
+				const link = requireConnectedLink();
+				return pingRoundTrips.sendAndAwait(clock.now(), async () => {
+					const ping = { type: "ping" };
+					frameLog.push({
+						direction: "sent",
+						frame: ping
+					});
+					await link.send(ping);
+					emit();
+				}, timeoutMs);
+			},
 			setToken(token) {
 				currentToken = token;
 			},
 			async sendManageRequest(command, scope, targetDevice, token, timeoutMs) {
-				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				requireConnectedLink();
 				if (targetDevice !== void 0) await ensureRelayPairing(targetDevice);
 				const frame = buildManageRequest(command, scope, token);
 				const requestId = frame["request-id"];
@@ -418,7 +476,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				})]);
 			},
 			async sendRevocationAnnounce(entries) {
-				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				requireConnectedLink();
 				const frame = {
 					type: "revocation-announce",
 					entries: [...entries]
@@ -431,7 +489,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				emit();
 			},
 			async sendGossipUpdate(extensions) {
-				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				requireConnectedLink();
 				const frame = buildSelfAdvert(extensions);
 				frameLog.push({
 					direction: "sent",
@@ -441,7 +499,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				emit();
 			},
 			async sendDataFrame(frame) {
-				if (connection === null || state.status !== "connected") throw new Error("not connected");
+				requireConnectedLink();
 				frameLog.push({
 					direction: "sent",
 					frame
@@ -460,6 +518,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					reconnectTimer = null;
 				}
 				rejectPendingManageRequests("connection closed before a response arrived");
+				pingRoundTrips.rejectAll("connection closed before a pong arrived");
 				if (connection !== null) await connection.close();
 				if (state.status === "connected" || state.status === "connecting" || state.status === "reconnecting") state = {
 					status: "closed",
@@ -471,8 +530,8 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		}
 	};
 }
-function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null, addresses = []) {
-	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address), void 0, addresses);
+function createMeshSession(transport, identity, clock = { now: () => Date.now() }, reconnect = null, addresses = [], onPeerAdvert) {
+	const { session } = createSessionCore(identity, clock, reconnect, async (address) => transport.connect(address), onPeerAdvert, addresses);
 	return session;
 }
 /** 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. */
@@ -484,9 +543,11 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 	});
 	let peerDeviceIdResolved = false;
 	const { session, wireUpConnection } = createSessionCore(identity, clock, null, null, (advert) => {
-		if (peerDeviceIdResolved) return;
-		peerDeviceIdResolved = true;
-		resolvePeerDeviceId?.(advert.device);
+		if (!peerDeviceIdResolved) {
+			peerDeviceIdResolved = true;
+			resolvePeerDeviceId?.(advert.device);
+		}
+		options.onPeerAdvert?.(advert);
 	}, options.addresses, options.onFrame, options.onSessionEnd);
 	await wireUpConnection(connection, options.label ?? "accepted", localDomains);
 	return {