wire-mesh-core 3.11.0 → 4.0.1

package/dist/domain/coordinator-election.cjs

@@ -11,6 +11,10 @@ function compareDeviceIds(a, b) {
 	}
 	return a.length - b.length;
 }
+/** Whether a claim at this term can be superseded by a later claim: a non-negative safe integer strictly below Number.MAX_SAFE_INTEGER, so that term + 1 is still an exactly represented, strictly greater integer. Above that ceiling a double cannot count on (2 ** 53 + 1 === 2 ** 53), and an incumbent there could never be superseded, so a device that named itself holder would keep the role for good even after it had gone. */
+function isSupersedableTerm(term) {
+	return Number.isSafeInteger(term) && term >= 0 && term < Number.MAX_SAFE_INTEGER;
+}
 var CoordinatorElection = class {
 	ownDevice;
 	incumbent;
@@ -26,12 +30,15 @@ var CoordinatorElection = class {
 		return this.incumbent !== void 0 && compareDeviceIds(this.incumbent.coordinator, this.ownDevice) === 0;
 	}
 	/**
-	* Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
+	* Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Throws a RangeError when that term is not one peers accept (isSupersedableTerm), which only happens when the incumbent already sits at the highest term the election accepts. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
 	*/
 	claim(capacityHint) {
+		const lastTerm = this.incumbent?.term ?? -1;
+		const term = lastTerm + 1;
+		if (!isSupersedableTerm(term)) throw new RangeError(`the incumbent's term ${String(lastTerm)} leaves no term a claim can be raised to`);
 		const frame = {
 			type: "coordinator",
-			term: (this.incumbent?.term ?? -1) + 1,
+			term,
 			coordinator: this.ownDevice,
 			...capacityHint !== void 0 ? { "capacity-hint": capacityHint } : {}
 		};
@@ -55,9 +62,10 @@ var CoordinatorElection = class {
 		};
 	}
 	/**
-	* Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it).
+	* Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it); "rejected" means the claim's term is not supersedable (isSupersedableTerm), so it is dropped unevaluated and the caller should neither gossip nor answer it.
 	*/
 	evaluate(frame) {
+		if (!isSupersedableTerm(frame.term)) return { outcome: "rejected" };
 		const previous = this.incumbent;
 		if (previous === void 0 || frame.term > previous.term || frame.term === previous.term && compareDeviceIds(frame.coordinator, previous.coordinator) < 0) {
 			this.incumbent = {
@@ -79,3 +87,4 @@ var CoordinatorElection = class {
 //#endregion
 exports.CoordinatorElection = CoordinatorElection;
 exports.compareDeviceIds = compareDeviceIds;
+exports.isSupersedableTerm = isSupersedableTerm;

package/dist/domain/coordinator-election.d.cts

@@ -8,13 +8,17 @@ export interface CoordinatorClaim {
 }
 /** Bytewise "lowest device-id" comparison, the equal-term tiebreak the spec names: shorter is lower when one id is a prefix of the other, and equal ids compare equal. Device-ids are a fixed 32 bytes today, so the prefix branch is completeness rather than a live case. */
 export declare function compareDeviceIds(a: DeviceId, b: DeviceId): number;
-/** What evaluating an incoming claim concluded, so the caller can react without re-deriving the comparison: "accepted" means this claim is now the incumbent (it superseded a previous one, or there was none), "retained" means the incumbent survived (the incoming claim was stale, or lost the equal-term tiebreak), and the incumbent is returned either way so a caller squashing a stale claim re-announces exactly what it already holds. */
+/** Whether a claim at this term can be superseded by a later claim: a non-negative safe integer strictly below Number.MAX_SAFE_INTEGER, so that term + 1 is still an exactly represented, strictly greater integer. Above that ceiling a double cannot count on (2 ** 53 + 1 === 2 ** 53), and an incumbent there could never be superseded, so a device that named itself holder would keep the role for good even after it had gone. */
+export declare function isSupersedableTerm(term: number): boolean;
+/** What evaluating an incoming claim concluded, so the caller can react without re-deriving the comparison: "accepted" means this claim is now the incumbent (it superseded a previous one, or there was none), "retained" means the incumbent survived (the incoming claim was stale, or lost the equal-term tiebreak), and the incumbent is returned either way so a caller squashing a stale claim re-announces exactly what it already holds. "rejected" means the claim's term is not one a later claim can supersede (isSupersedableTerm), so it was never compared: the incumbent, if any, is untouched, and there is nothing to answer it with. */
 export type EvaluationOutcome = {
   outcome: "accepted";
   incumbent: CoordinatorClaim;
 } | {
   outcome: "retained";
   incumbent: CoordinatorClaim;
+} | {
+  outcome: "rejected";
 };
 export interface CoordinatorElectionOptions {
   /** This device's own id: the coordinator named by a claim this side mints. */
@@ -29,7 +33,7 @@ export declare class CoordinatorElection {
   /** Whether this side's own device is the incumbent. */
   isSelf(): boolean;
   /**
-   * Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
+   * Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Throws a RangeError when that term is not one peers accept (isSupersedableTerm), which only happens when the incumbent already sits at the highest term the election accepts. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
    */
   claim(capacityHint?: number): CoordinatorFrame;
   /**
@@ -37,7 +41,7 @@ export declare class CoordinatorElection {
    */
   announceCurrent(): CoordinatorFrame | undefined;
   /**
-   * Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it).
+   * Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it); "rejected" means the claim's term is not supersedable (isSupersedableTerm), so it is dropped unevaluated and the caller should neither gossip nor answer it.
    */
   evaluate(frame: Readonly<CoordinatorFrame>): EvaluationOutcome;
 }

package/dist/domain/coordinator-election.d.mts

@@ -8,13 +8,17 @@ export interface CoordinatorClaim {
 }
 /** Bytewise "lowest device-id" comparison, the equal-term tiebreak the spec names: shorter is lower when one id is a prefix of the other, and equal ids compare equal. Device-ids are a fixed 32 bytes today, so the prefix branch is completeness rather than a live case. */
 export declare function compareDeviceIds(a: DeviceId, b: DeviceId): number;
-/** What evaluating an incoming claim concluded, so the caller can react without re-deriving the comparison: "accepted" means this claim is now the incumbent (it superseded a previous one, or there was none), "retained" means the incumbent survived (the incoming claim was stale, or lost the equal-term tiebreak), and the incumbent is returned either way so a caller squashing a stale claim re-announces exactly what it already holds. */
+/** Whether a claim at this term can be superseded by a later claim: a non-negative safe integer strictly below Number.MAX_SAFE_INTEGER, so that term + 1 is still an exactly represented, strictly greater integer. Above that ceiling a double cannot count on (2 ** 53 + 1 === 2 ** 53), and an incumbent there could never be superseded, so a device that named itself holder would keep the role for good even after it had gone. */
+export declare function isSupersedableTerm(term: number): boolean;
+/** What evaluating an incoming claim concluded, so the caller can react without re-deriving the comparison: "accepted" means this claim is now the incumbent (it superseded a previous one, or there was none), "retained" means the incumbent survived (the incoming claim was stale, or lost the equal-term tiebreak), and the incumbent is returned either way so a caller squashing a stale claim re-announces exactly what it already holds. "rejected" means the claim's term is not one a later claim can supersede (isSupersedableTerm), so it was never compared: the incumbent, if any, is untouched, and there is nothing to answer it with. */
 export type EvaluationOutcome = {
   outcome: "accepted";
   incumbent: CoordinatorClaim;
 } | {
   outcome: "retained";
   incumbent: CoordinatorClaim;
+} | {
+  outcome: "rejected";
 };
 export interface CoordinatorElectionOptions {
   /** This device's own id: the coordinator named by a claim this side mints. */
@@ -29,7 +33,7 @@ export declare class CoordinatorElection {
   /** Whether this side's own device is the incumbent. */
   isSelf(): boolean;
   /**
-   * Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
+   * Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Throws a RangeError when that term is not one peers accept (isSupersedableTerm), which only happens when the incumbent already sits at the highest term the election accepts. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
    */
   claim(capacityHint?: number): CoordinatorFrame;
   /**
@@ -37,7 +41,7 @@ export declare class CoordinatorElection {
    */
   announceCurrent(): CoordinatorFrame | undefined;
   /**
-   * Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it).
+   * Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it); "rejected" means the claim's term is not supersedable (isSupersedableTerm), so it is dropped unevaluated and the caller should neither gossip nor answer it.
    */
   evaluate(frame: Readonly<CoordinatorFrame>): EvaluationOutcome;
 }

package/dist/domain/coordinator-election.mjs

@@ -10,6 +10,10 @@ function compareDeviceIds(a, b) {
 	}
 	return a.length - b.length;
 }
+/** Whether a claim at this term can be superseded by a later claim: a non-negative safe integer strictly below Number.MAX_SAFE_INTEGER, so that term + 1 is still an exactly represented, strictly greater integer. Above that ceiling a double cannot count on (2 ** 53 + 1 === 2 ** 53), and an incumbent there could never be superseded, so a device that named itself holder would keep the role for good even after it had gone. */
+function isSupersedableTerm(term) {
+	return Number.isSafeInteger(term) && term >= 0 && term < Number.MAX_SAFE_INTEGER;
+}
 var CoordinatorElection = class {
 	ownDevice;
 	incumbent;
@@ -25,12 +29,15 @@ var CoordinatorElection = class {
 		return this.incumbent !== void 0 && compareDeviceIds(this.incumbent.coordinator, this.ownDevice) === 0;
 	}
 	/**
-	* Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
+	* Claims the role for this side's own device at a term above every term seen so far (lastTerm + 1, so a first-ever claim is term 0), and returns the frame to gossip. Throws a RangeError when that term is not one peers accept (isSupersedableTerm), which only happens when the incumbent already sits at the highest term the election accepts. Claiming over a claim this side already holds is a deliberate takeover: it raises the term, which is exactly what a peer recovering the role after losing track of the mesh should do, and what a routine refresh should not (announceCurrent exists for that).
 	*/
 	claim(capacityHint) {
+		const lastTerm = this.incumbent?.term ?? -1;
+		const term = lastTerm + 1;
+		if (!isSupersedableTerm(term)) throw new RangeError(`the incumbent's term ${String(lastTerm)} leaves no term a claim can be raised to`);
 		const frame = {
 			type: "coordinator",
-			term: (this.incumbent?.term ?? -1) + 1,
+			term,
 			coordinator: this.ownDevice,
 			...capacityHint !== void 0 ? { "capacity-hint": capacityHint } : {}
 		};
@@ -54,9 +61,10 @@ var CoordinatorElection = class {
 		};
 	}
 	/**
-	* Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it).
+	* Evaluates an incoming claim against the one this side currently accepts: a strictly higher term always wins; an equal term breaks by lowest device-id, so an incoming claim naming a lower device-id than the incumbent's takes the role and one naming a higher device-id loses; a lower term never wins. "accepted" means the incumbent changed (the caller should gossip the new incumbent onward so the supersession propagates); "retained" means it did not (the caller may answer a stale claim by re-gossiping announceCurrent(), and should drop a lost equal-term claim it originated, since the tiebreak has settled it); "rejected" means the claim's term is not supersedable (isSupersedableTerm), so it is dropped unevaluated and the caller should neither gossip nor answer it.
 	*/
 	evaluate(frame) {
+		if (!isSupersedableTerm(frame.term)) return { outcome: "rejected" };
 		const previous = this.incumbent;
 		if (previous === void 0 || frame.term > previous.term || frame.term === previous.term && compareDeviceIds(frame.coordinator, previous.coordinator) < 0) {
 			this.incumbent = {
@@ -76,4 +84,4 @@ var CoordinatorElection = class {
 	}
 };
 //#endregion
-export { CoordinatorElection, compareDeviceIds };
+export { CoordinatorElection, compareDeviceIds, isSupersedableTerm };

package/dist/domain/mesh-session.cjs

@@ -285,6 +285,15 @@ function createRelayChannels(identity, sendHello) {
 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;
+/**
+* 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.
+*/
+const FRAME_LOG_WINDOW = 256;
 function localHandshake(domains) {
 	return {
 		type: "handshake",
@@ -301,6 +310,11 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	let handshake = { status: "pending" };
 	const directory = /* @__PURE__ */ new Map();
 	const frameLog = [];
+	/** Keeps the frame log at its recent-activity window: newest entries at the end, the oldest dropped once the window is full. */
+	function recordFrame(entry) {
+		frameLog.push(entry);
+		if (frameLog.length > 256) frameLog.splice(0, frameLog.length - 256);
+	}
 	let feedCancelled = false;
 	const eventQueue = require_domain_async_queue.createAsyncQueue();
 	let handshakeTimer = null;
@@ -317,7 +331,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	const pendingManageRequests = /* @__PURE__ */ new Map();
 	const relayChannels = createRelayChannels(identity, async (peer, hello) => {
 		if (connection === null) throw new Error("not connected");
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: hello
 		});
@@ -399,7 +413,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					"request-id": requestId,
 					outcome
 				};
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame: response
 				});
@@ -417,7 +431,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		if (frame.type === "relay-data") {
 			const inner = require_adapters_frame_codec.tryDecodeFrame(frame.payload);
 			if (inner?.type === "secure-hello") {
-				frameLog.push({
+				recordFrame({
 					direction: "received",
 					frame: inner
 				});
@@ -427,13 +441,13 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			if (inner?.type === "secure-data") {
 				const opened = await relayChannels.open(inner, frame["from-device"]);
 				if (opened?.frame.type === "manage-response") {
-					frameLog.push({
+					recordFrame({
 						direction: "received",
 						frame: opened.frame
 					});
 					applyManageResponse(opened.frame, opened.from);
 				} else if (opened !== void 0 && require_domain_hub_mailbox.isDataFrame(opened.frame)) {
-					frameLog.push({
+					recordFrame({
 						direction: "received",
 						frame: opened.frame
 					});
@@ -443,7 +457,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 						...frame["to-device"] !== void 0 ? { toDevice: frame["to-device"] } : {}
 					});
 				} else if (opened?.frame.type === "manage-request") {
-					frameLog.push({
+					recordFrame({
 						direction: "received",
 						frame: opened.frame
 					});
@@ -454,13 +468,13 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				}
 				return;
 			}
-			frameLog.push({
+			recordFrame({
 				direction: "received",
 				frame
 			});
 			return;
 		}
-		frameLog.push({
+		recordFrame({
 			direction: "received",
 			frame
 		});
@@ -490,7 +504,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			type: "relay-connect",
 			"target-device": targetDevice
 		};
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: relayConnect
 		});
@@ -595,14 +609,14 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			address,
 			handshake
 		};
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: localHandshakeSent
 		});
 		await connection.send(localHandshakeSent);
 		emit();
 		const selfAdvert = await buildSelfAdvert();
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: selfAdvert
 		});
@@ -660,7 +674,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendPing() {
 				const link = requireConnectedLink();
 				const ping = { type: "ping" };
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame: ping
 				});
@@ -671,7 +685,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				const link = requireConnectedLink();
 				return pingRoundTrips.sendAndAwait(clock.now(), async () => {
 					const ping = { type: "ping" };
-					frameLog.push({
+					recordFrame({
 						direction: "sent",
 						frame: ping
 					});
@@ -694,7 +708,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 						expectedFrom: targetDevice
 					});
 				});
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -731,7 +745,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					type: "revocation-announce",
 					entries: [...entries]
 				};
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -741,7 +755,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendCoordinatorClaim(frame) {
 				requireConnectedLink();
 				const claim = { ...frame };
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame: claim
 				});
@@ -751,7 +765,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendGossipUpdate(extensions) {
 				requireConnectedLink();
 				const frame = await buildSelfAdvert(extensions);
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -764,7 +778,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendDataFrame(frame, targetDevice) {
 				requireConnectedLink();
 				if (targetDevice !== void 0) await ensureRelayPairing(targetDevice);
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -821,6 +835,7 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 	};
 }
 //#endregion
+exports.FRAME_LOG_WINDOW = FRAME_LOG_WINDOW;
 exports.HANDSHAKE_TIMEOUT_MS = HANDSHAKE_TIMEOUT_MS;
 exports.acceptMeshSession = acceptMeshSession;
 exports.createMeshSession = createMeshSession;

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

@@ -70,13 +70,22 @@ export interface SessionEvent {
   state: ConnectionState;
   /** The peer directory as of this event: latest peer-advert per device-id, in first-heard order. */
   directory: readonly DirectoryEntry[];
-  /** Every frame that crossed the connection, sent or received, in order. */
+  /** 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[];
 }
 export 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.
+ */
+export declare const FRAME_LOG_WINDOW = 256;
 export interface FrameLogEntry {
   direction: "sent" | "received";
   frame: Frame;

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

@@ -70,13 +70,22 @@ export interface SessionEvent {
   state: ConnectionState;
   /** The peer directory as of this event: latest peer-advert per device-id, in first-heard order. */
   directory: readonly DirectoryEntry[];
-  /** Every frame that crossed the connection, sent or received, in order. */
+  /** 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[];
 }
 export 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.
+ */
+export declare const FRAME_LOG_WINDOW = 256;
 export interface FrameLogEntry {
   direction: "sent" | "received";
   frame: Frame;

package/dist/domain/mesh-session.mjs

@@ -284,6 +284,15 @@ function createRelayChannels(identity, sendHello) {
 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;
+/**
+* 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.
+*/
+const FRAME_LOG_WINDOW = 256;
 function localHandshake(domains) {
 	return {
 		type: "handshake",
@@ -300,6 +309,11 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	let handshake = { status: "pending" };
 	const directory = /* @__PURE__ */ new Map();
 	const frameLog = [];
+	/** Keeps the frame log at its recent-activity window: newest entries at the end, the oldest dropped once the window is full. */
+	function recordFrame(entry) {
+		frameLog.push(entry);
+		if (frameLog.length > 256) frameLog.splice(0, frameLog.length - 256);
+	}
 	let feedCancelled = false;
 	const eventQueue = createAsyncQueue();
 	let handshakeTimer = null;
@@ -316,7 +330,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 	const pendingManageRequests = /* @__PURE__ */ new Map();
 	const relayChannels = createRelayChannels(identity, async (peer, hello) => {
 		if (connection === null) throw new Error("not connected");
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: hello
 		});
@@ -398,7 +412,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					"request-id": requestId,
 					outcome
 				};
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame: response
 				});
@@ -416,7 +430,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		if (frame.type === "relay-data") {
 			const inner = tryDecodeFrame(frame.payload);
 			if (inner?.type === "secure-hello") {
-				frameLog.push({
+				recordFrame({
 					direction: "received",
 					frame: inner
 				});
@@ -426,13 +440,13 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			if (inner?.type === "secure-data") {
 				const opened = await relayChannels.open(inner, frame["from-device"]);
 				if (opened?.frame.type === "manage-response") {
-					frameLog.push({
+					recordFrame({
 						direction: "received",
 						frame: opened.frame
 					});
 					applyManageResponse(opened.frame, opened.from);
 				} else if (opened !== void 0 && isDataFrame(opened.frame)) {
-					frameLog.push({
+					recordFrame({
 						direction: "received",
 						frame: opened.frame
 					});
@@ -442,7 +456,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 						...frame["to-device"] !== void 0 ? { toDevice: frame["to-device"] } : {}
 					});
 				} else if (opened?.frame.type === "manage-request") {
-					frameLog.push({
+					recordFrame({
 						direction: "received",
 						frame: opened.frame
 					});
@@ -453,13 +467,13 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				}
 				return;
 			}
-			frameLog.push({
+			recordFrame({
 				direction: "received",
 				frame
 			});
 			return;
 		}
-		frameLog.push({
+		recordFrame({
 			direction: "received",
 			frame
 		});
@@ -489,7 +503,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			type: "relay-connect",
 			"target-device": targetDevice
 		};
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: relayConnect
 		});
@@ -594,14 +608,14 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			address,
 			handshake
 		};
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: localHandshakeSent
 		});
 		await connection.send(localHandshakeSent);
 		emit();
 		const selfAdvert = await buildSelfAdvert();
-		frameLog.push({
+		recordFrame({
 			direction: "sent",
 			frame: selfAdvert
 		});
@@ -659,7 +673,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendPing() {
 				const link = requireConnectedLink();
 				const ping = { type: "ping" };
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame: ping
 				});
@@ -670,7 +684,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				const link = requireConnectedLink();
 				return pingRoundTrips.sendAndAwait(clock.now(), async () => {
 					const ping = { type: "ping" };
-					frameLog.push({
+					recordFrame({
 						direction: "sent",
 						frame: ping
 					});
@@ -693,7 +707,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 						expectedFrom: targetDevice
 					});
 				});
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -730,7 +744,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 					type: "revocation-announce",
 					entries: [...entries]
 				};
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -740,7 +754,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendCoordinatorClaim(frame) {
 				requireConnectedLink();
 				const claim = { ...frame };
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame: claim
 				});
@@ -750,7 +764,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendGossipUpdate(extensions) {
 				requireConnectedLink();
 				const frame = await buildSelfAdvert(extensions);
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -763,7 +777,7 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			async sendDataFrame(frame, targetDevice) {
 				requireConnectedLink();
 				if (targetDevice !== void 0) await ensureRelayPairing(targetDevice);
-				frameLog.push({
+				recordFrame({
 					direction: "sent",
 					frame
 				});
@@ -820,4 +834,4 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 	};
 }
 //#endregion
-export { HANDSHAKE_TIMEOUT_MS, acceptMeshSession, createMeshSession };
+export { FRAME_LOG_WINDOW, HANDSHAKE_TIMEOUT_MS, acceptMeshSession, createMeshSession };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "3.11.0",
+  "version": "4.0.1",
   "dependencies": {
     "cbor2": "2.3.0",
     "cddl.js": "1.0.1",