maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.5.20260830

package/node_modules/@maka/runtime-host/dist/peer-mesh/model.js

@@ -19,6 +19,7 @@
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign, timingSafeEqual, verify, } from 'node:crypto';
 import { decodePeerMeshInvitation as decodePeerMeshInvitationWire, } from '../protocol/peer-mesh.js';
 import { PEER_MESH_MAX_MEMBERS, PEER_MESH_MAX_ROUTE_HINTS, PEER_MESH_ROUTE_RECORD_MAX_BYTES, } from './limits.js';
+import { canonicalPeerMeshDisplayName } from './display-name.js';
 export { PEER_MESH_MAX_INVITATION_RECORDS, PEER_MESH_MAX_MEMBERS, PEER_MESH_MAX_MESHES, PEER_MESH_MAX_PENDING_INVITATIONS, PEER_MESH_MAX_ROUTE_HINTS, PEER_MESH_MAX_TRANSIT_ADDRESSES_PER_RELAY, PEER_MESH_MAX_TRANSIT_RELAY_ADDRESSES, PEER_MESH_ROUTE_RECORD_MAX_BYTES, } from './limits.js';
 export function generatePeerMeshAuthorityKeyPair() {
     const { publicKey, privateKey } = generateKeyPairSync('ed25519');
@@ -114,13 +115,12 @@ export function validatePeerMeshInvitation(value) {
     });
 }
 export function canonicalPeerMeshRoster(value) {
-    const record = exactObject(value, 'Peer Mesh roster', [
-        'version',
-        'meshId',
-        'revision',
-        'members',
-        'closed',
-    ]);
+    const keys = ['version', 'meshId', 'revision', 'members', 'closed'];
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        if (Object.hasOwn(value, 'displayName'))
+            keys.push('displayName');
+    }
+    const record = exactObject(value, 'Peer Mesh roster', keys);
     if (record.version !== 1)
         throw new Error('Unsupported Peer Mesh roster version');
     const members = stringArray(record.members, 'members', PEER_MESH_MAX_MEMBERS, 256)
@@ -137,6 +137,9 @@ export function canonicalPeerMeshRoster(value) {
         revision: integer(record.revision, 'revision', 1),
         members: Object.freeze(members),
         closed: record.closed,
+        ...(record.displayName === undefined
+            ? {}
+            : { displayName: canonicalPeerMeshDisplayName(record.displayName) }),
     });
 }
 export function decodeAuthorityTarget(value) {
@@ -152,22 +155,23 @@ export function decodeAuthorityTarget(value) {
     });
 }
 export function canonicalPeerMeshRouteRecord(value) {
-    const baseKeys = [
-        'version',
-        'peerId',
-        'sequence',
-        'expiresAt',
-        'routeHints',
-        'coordinationRelays',
-    ];
-    const record = exactObject(value, 'Peer Mesh route record', value &&
-        typeof value === 'object' &&
-        !Array.isArray(value) &&
-        Object.hasOwn(value, 'transitMeshId')
-        ? [...baseKeys, 'transitMeshId']
-        : baseKeys);
+    const keys = ['version', 'peerId', 'sequence', 'expiresAt', 'routeHints', 'coordinationRelays'];
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        if (Object.hasOwn(value, 'endpointKind'))
+            keys.push('endpointKind');
+        if (Object.hasOwn(value, 'displayName'))
+            keys.push('displayName');
+        if (Object.hasOwn(value, 'transitMeshId'))
+            keys.push('transitMeshId');
+    }
+    const record = exactObject(value, 'Peer Mesh route record', keys);
     if (record.version !== 1)
         throw new Error('Unsupported Peer Mesh route record version');
+    if (record.endpointKind !== undefined &&
+        record.endpointKind !== 'client' &&
+        record.endpointKind !== 'host') {
+        throw new Error('Invalid Peer Mesh endpoint kind');
+    }
     const route = Object.freeze({
         version: 1,
         peerId: token(record.peerId, 'peerId', 256),
@@ -175,6 +179,10 @@ export function canonicalPeerMeshRouteRecord(value) {
         expiresAt: integer(record.expiresAt, 'route expiry', 1),
         routeHints: Object.freeze(addressArray(record.routeHints, 'routeHints')),
         coordinationRelays: Object.freeze(addressArray(record.coordinationRelays, 'coordinationRelays')),
+        ...(record.endpointKind === undefined ? {} : { endpointKind: record.endpointKind }),
+        ...(record.displayName === undefined
+            ? {}
+            : { displayName: canonicalPeerMeshDisplayName(record.displayName) }),
         ...(record.transitMeshId === undefined
             ? {}
             : { transitMeshId: string(record.transitMeshId, 'transitMeshId', 128) }),
@@ -201,6 +209,8 @@ export function decodeSignedPeerMeshRouteRecord(value) {
 export function peerMeshRouteRecordSigningBytes(route) {
     return Buffer.from(`maka.peer-mesh.route.v1\n${JSON.stringify({
         coordinationRelays: route.coordinationRelays,
+        ...(route.displayName ? { displayName: route.displayName } : {}),
+        ...(route.endpointKind ? { endpointKind: route.endpointKind } : {}),
         expiresAt: route.expiresAt,
         peerId: route.peerId,
         routeHints: route.routeHints,
@@ -212,6 +222,7 @@ export function peerMeshRouteRecordSigningBytes(route) {
 function encodeRoster(roster) {
     return Buffer.from(`maka.peer-mesh.roster.v1\n${JSON.stringify({
         closed: roster.closed,
+        ...(roster.displayName ? { displayName: roster.displayName } : {}),
         members: roster.members,
         meshId: roster.meshId,
         revision: roster.revision,

package/node_modules/@maka/runtime-host/dist/peer-mesh/node.js

@@ -18,6 +18,7 @@
  */
 import { setTimeout as delay } from 'node:timers/promises';
 import { canonicalPeerMeshRoster, canonicalPeerMeshRouteRecord, createPeerMeshInvitationSecret, validatePeerMeshInvitation, decodeSignedPeerMeshRoster, decodeSignedPeerMeshRouteRecord, generatePeerMeshAuthorityKeyPair, matchesPeerMeshInvitationSecret, PEER_MESH_MAX_MEMBERS, PEER_MESH_MAX_MESHES, PEER_MESH_MAX_INVITATION_RECORDS, PEER_MESH_MAX_PENDING_INVITATIONS, PEER_MESH_MAX_TRANSIT_ADDRESSES_PER_RELAY, PEER_MESH_MAX_TRANSIT_RELAY_ADDRESSES, peerMeshRouteRecordSigningBytes, peerMeshId, peerMeshInvitationSecretDigest, signPeerMeshRoster, } from './model.js';
+import { canonicalPeerMeshDisplayName } from './display-name.js';
 import { authorityKeys, openPeerMeshStateStore, } from './store.js';
 const CONTROL_FRAME_MAX_BYTES = 64 * 1024;
 const DEFAULT_INVITATION_TTL_MS = 15 * 60 * 1_000;
@@ -47,6 +48,7 @@ export async function openPeerMeshNode(input) {
 class PeerMeshNodeImpl {
     #store;
     #peer;
+    #endpointKind;
     #now;
     #activeControlStreams = new Set();
     #lifetime = new AbortController();
@@ -60,6 +62,7 @@ class PeerMeshNodeImpl {
     constructor(input) {
         this.#store = input.store;
         this.#peer = input.peer;
+        this.#endpointKind = input.endpointKind;
         this.#now = input.now ?? Date.now;
     }
     async initialize() {
@@ -71,13 +74,64 @@ class PeerMeshNodeImpl {
         this.#assertOpen();
         return this.#peer.identity().peerId;
     }
+    displayName() {
+        this.#assertOpen();
+        return this.#store.read().displayName ?? undefined;
+    }
+    setDisplayName(displayName) {
+        return this.#admitMesh(async () => {
+            const canonical = displayName === null ? null : canonicalPeerMeshDisplayName(displayName);
+            await this.#store.mutate(async (current) => {
+                if (current.displayName === canonical)
+                    return { state: current, result: undefined };
+                const state = { ...current, displayName: canonical };
+                const localPeerId = this.#peer.identity().peerId;
+                if (!state.meshes.some((mesh) => isActiveMembership(mesh, localPeerId))) {
+                    return { state, result: undefined };
+                }
+                const route = await this.#signLocalRoute(state);
+                return {
+                    state: {
+                        ...state,
+                        routes: mergeRoutes(state.routes, [route], this.#now()),
+                    },
+                    result: undefined,
+                };
+            });
+            void this.reconcile().catch(() => undefined);
+        });
+    }
+    setMeshDisplayName(meshId, displayName) {
+        return this.#admitMesh(async () => {
+            const canonical = displayName === null ? undefined : canonicalPeerMeshDisplayName(displayName);
+            await this.#store.mutate((current) => {
+                const state = requireAuthority(current.meshes, meshId);
+                if (state.roster.roster.closed)
+                    throw new Error('Peer Mesh is closed');
+                if (state.roster.roster.displayName === canonical)
+                    return { state: current, result: undefined };
+                const { displayName: _currentDisplayName, ...currentRoster } = state.roster.roster;
+                const roster = signPeerMeshRoster(canonicalPeerMeshRoster({
+                    ...currentRoster,
+                    revision: state.roster.roster.revision + 1,
+                    ...(canonical ? { displayName: canonical } : {}),
+                }), authorityKeys(state));
+                return {
+                    state: { ...current, meshes: replaceMesh(current.meshes, { ...state, roster }) },
+                    result: undefined,
+                };
+            });
+            const stored = this.#store.read();
+            return peerMeshStatus(requireAuthority(stored.meshes, meshId), this.#peer.identity(), this.#endpointKind, stored.routes, this.#now());
+        });
+    }
     status() {
         this.#assertOpen();
         const identity = this.#peer.identity();
         const stored = this.#store.read();
         return Object.freeze(stored.meshes
             .filter((state) => isActiveMembership(state, identity.peerId))
-            .map((state) => peerMeshStatus(state, identity, stored.routes, this.#now())));
+            .map((state) => peerMeshStatus(state, identity, this.#endpointKind, stored.routes, this.#now())));
     }
     create() {
         return this.#admitMesh(async () => {
@@ -116,7 +170,7 @@ class PeerMeshNodeImpl {
                 };
             });
             const stored = this.#store.read();
-            return peerMeshStatus(findMesh(stored.meshes, state.roster.roster.meshId), identity, stored.routes, now);
+            return peerMeshStatus(findMesh(stored.meshes, state.roster.roster.meshId), identity, this.#endpointKind, stored.routes, now);
         });
     }
     invite(meshId, input = {}) {
@@ -211,6 +265,7 @@ class PeerMeshNodeImpl {
                     throw new Error('Peer Mesh authority returned an unrelated roster');
                 }
                 const routes = await this.#validateRoutes(response.routes, roster, this.#now());
+                operationSignal.throwIfAborted();
                 await this.#store.mutate((current) => {
                     const existing = findMesh(current.meshes, invitation.meshId);
                     if (existing?.role === 'authority') {
@@ -246,7 +301,7 @@ class PeerMeshNodeImpl {
                 await this.#refreshLocalRoute();
                 await this.#reconcileTransit();
                 const stored = this.#store.read();
-                return peerMeshStatus(findMesh(stored.meshes, invitation.meshId), identity, stored.routes);
+                return peerMeshStatus(findMesh(stored.meshes, invitation.meshId), identity, this.#endpointKind, stored.routes);
             }
             finally {
                 await stream.close().catch(() => undefined);
@@ -366,12 +421,31 @@ class PeerMeshNodeImpl {
             transitRelayPeerIds: Object.freeze(transitRelayPeerIds),
         });
     }
+    async prepareRoutes(peerId, signal) {
+        this.#assertOpen();
+        signal.throwIfAborted();
+        const localPeerId = this.#peer.identity().peerId;
+        const stored = this.#store.read();
+        const visible = stored.meshes.some((mesh) => isActiveMembership(mesh, localPeerId) && mesh.roster.roster.members.includes(peerId));
+        if (!visible)
+            return;
+        if (stored.routes.some(({ route }) => route.peerId === peerId && route.expiresAt > this.#now())) {
+            return;
+        }
+        await this.reconcile(signal);
+    }
     reconcile(signal) {
         if (this.#lifetime.signal.aborted)
             return Promise.reject(new Error('Peer Mesh node is closed'));
-        const task = this.#reconcileTail.then(() => this.#reconcile(signal));
-        this.#reconcileTail = task.then(() => undefined, () => undefined);
-        return task;
+        const previous = this.#reconcileTail;
+        let release;
+        const turn = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.#reconcileTail = previous.then(() => turn);
+        return waitForTurn(previous, signal)
+            .then(() => this.#reconcile(signal))
+            .finally(release);
     }
     async serve() {
         if (this.#lifetime.signal.aborted)
@@ -435,7 +509,9 @@ class PeerMeshNodeImpl {
         const pending = [];
         const gossipCursor = this.#gossipCursor;
         this.#gossipCursor = (this.#gossipCursor + 1) % PEER_MESH_MAX_MEMBERS;
+        const now = this.#now();
         for (const [index, state] of memberships.entries()) {
+            const authorityRoute = stored.routes.find(({ route }) => route.peerId === state.authority.peerId);
             const targets = [currentAuthorityTarget(state, stored.routes)];
             const gossipRoutes = state.roster.roster.members
                 .filter((peerId) => peerId !== identity.peerId && peerId !== state.authority.peerId)
@@ -446,13 +522,18 @@ class PeerMeshNodeImpl {
             if (gossipRoutes.length > 0) {
                 targets.push(gossipRoutes[(gossipCursor + index) % gossipRoutes.length]);
             }
-            pending.push({ meshId: state.roster.roster.meshId, targets });
+            pending.push({
+                meshId: state.roster.roster.meshId,
+                targets,
+                authorityRouteExpired: authorityRoute !== undefined && authorityRoute.route.expiresAt <= now,
+            });
         }
         if (pending.length === 0)
             return;
         const start = this.#reconcileCursor % pending.length;
         const deadline = AbortSignal.timeout(RECONCILE_DEADLINE_MS);
         const operationSignal = AbortSignal.any([lifetimeSignal, deadline]);
+        const failures = [];
         let next = 0;
         const worker = async () => {
             while (!operationSignal.aborted) {
@@ -460,17 +541,14 @@ class PeerMeshNodeImpl {
                 next += 1;
                 if (offset >= pending.length)
                     return;
-                const { meshId, targets } = pending[(start + offset) % pending.length];
+                const { meshId, targets, authorityRouteExpired } = pending[(start + offset) % pending.length];
                 try {
-                    const outcomes = await Promise.allSettled(targets.map((target) => this.#syncPeer(meshId, target, operationSignal)));
-                    if (!outcomes.some(({ status }) => status === 'fulfilled')) {
-                        const failure = outcomes.find((outcome) => outcome.status === 'rejected');
-                        throw failure?.reason ?? new Error('Peer Mesh synchronization failed');
-                    }
+                    await this.#syncTargets(meshId, targets, authorityRouteExpired, operationSignal);
                 }
-                catch {
+                catch (error) {
                     if (lifetimeSignal.aborted)
                         lifetimeSignal.throwIfAborted();
+                    failures.push(error);
                     if (deadline.aborted)
                         return;
                 }
@@ -480,6 +558,46 @@ class PeerMeshNodeImpl {
         this.#reconcileCursor = (start + Math.min(next, pending.length)) % pending.length;
         await this.#reconcileTransit();
         lifetimeSignal.throwIfAborted();
+        if (failures.length > 0) {
+            throw new AggregateError(failures, 'Peer Mesh synchronization did not reach every membership');
+        }
+    }
+    async #syncTargets(meshId, targets, authorityRouteExpired, signal) {
+        if (!authorityRouteExpired || targets.length === 1) {
+            try {
+                await this.#syncPeer(meshId, targets[0], signal);
+            }
+            catch (authorityFailure) {
+                const fallbackTargets = targets.slice(1);
+                if (fallbackTargets.length === 0)
+                    throw authorityFailure;
+                await Promise.any(fallbackTargets.map((target) => this.#syncPeer(meshId, target, signal)));
+            }
+            return;
+        }
+        const controllers = targets.map(() => new AbortController());
+        const authorityPeerId = targets[0].peerId;
+        const attempts = targets.map(async (target, index) => {
+            await this.#syncPeer(meshId, target, AbortSignal.any([signal, controllers[index].signal]));
+            if (index > 0 && !this.#hasFreshRoute(meshId, authorityPeerId)) {
+                throw new Error('Peer Mesh gossip did not recover the authority route');
+            }
+        });
+        try {
+            await Promise.any(attempts);
+        }
+        finally {
+            for (const controller of controllers)
+                controller.abort();
+            await Promise.allSettled(attempts);
+        }
+    }
+    #hasFreshRoute(meshId, peerId) {
+        const stored = this.#store.read();
+        const mesh = findMesh(stored.meshes, meshId);
+        return Boolean(mesh &&
+            isActiveMembership(mesh, this.#peer.identity().peerId) &&
+            stored.routes.some(({ route }) => route.peerId === peerId && route.expiresAt > this.#now()));
     }
     async #syncPeer(meshId, target, signal) {
         for (let page = 0; page <= Math.ceil(PEER_MESH_MAX_MEMBERS / ROUTE_PAGE_SIZE); page += 1) {
@@ -492,10 +610,12 @@ class PeerMeshNodeImpl {
             const route = stored.routes.find((candidate) => candidate.route.peerId === localPeerId);
             if (!route)
                 throw new Error('Peer Mesh local route is unavailable');
+            const discovered = this.resolveRoutes(target.peerId);
             const stream = await this.#peer.connectMeshControl({
                 peerId: target.peerId,
-                routeHints: target.routeHints,
-                coordinationRelays: target.coordinationRelays,
+                routeHints: mergeAddresses(discovered?.routeHints ?? [], target.routeHints),
+                coordinationRelays: mergeAddresses(discovered?.coordinationRelays ?? [], target.coordinationRelays),
+                transitRelayPeerIds: discovered?.transitRelayPeerIds,
                 directDeadlineMs: CONNECT_DEADLINE_MS,
             }, signal);
             try {
@@ -527,31 +647,32 @@ class PeerMeshNodeImpl {
     }
     async #refreshLocalRouteOnce() {
         const identity = this.#peer.identity();
-        const current = this.#store.read();
-        const active = current.meshes.filter((state) => isActiveMembership(state, identity.peerId));
-        if (active.length === 0)
-            return undefined;
-        const existing = current.routes
-            .filter(({ route }) => route.peerId === identity.peerId)
-            .sort((left, right) => right.route.sequence - left.route.sequence)[0];
         const now = this.#now();
-        if (existing &&
-            existing.route.expiresAt > now + ROUTE_REFRESH_LEAD_MS &&
-            sameAddresses(existing.route.routeHints, identity.listenAddresses) &&
-            sameAddresses(existing.route.coordinationRelays, identity.coordinationRelays) &&
-            existing.route.transitMeshId === current.transitMeshId) {
-            return existing;
-        }
-        const route = await this.#signLocalRoute();
-        await this.#store.mutate((states) => ({
-            state: { ...states, routes: mergeRoutes(states.routes, [route], now) },
-            result: undefined,
-        }));
-        return route;
+        return this.#store.mutate(async (current) => {
+            if (!current.meshes.some((state) => isActiveMembership(state, identity.peerId))) {
+                return { state: current, result: undefined };
+            }
+            const existing = current.routes
+                .filter(({ route }) => route.peerId === identity.peerId)
+                .sort((left, right) => right.route.sequence - left.route.sequence)[0];
+            if (existing &&
+                existing.route.expiresAt > now + ROUTE_REFRESH_LEAD_MS &&
+                sameAddresses(existing.route.routeHints, identity.listenAddresses) &&
+                sameAddresses(existing.route.coordinationRelays, identity.coordinationRelays) &&
+                existing.route.endpointKind === this.#endpointKind &&
+                existing.route.displayName === (current.displayName ?? undefined) &&
+                existing.route.transitMeshId === current.transitMeshId) {
+                return { state: current, result: existing };
+            }
+            const route = await this.#signLocalRoute(current);
+            return {
+                state: { ...current, routes: mergeRoutes(current.routes, [route], now) },
+                result: route,
+            };
+        });
     }
-    async #signLocalRoute() {
+    async #signLocalRoute(stored = this.#store.read()) {
         const identity = this.#peer.identity();
-        const stored = this.#store.read();
         const maxSequence = stored.routes
             .filter(({ route }) => route.peerId === identity.peerId)
             .reduce((maximum, { route }) => Math.max(maximum, route.sequence), 0);
@@ -562,6 +683,8 @@ class PeerMeshNodeImpl {
             expiresAt: this.#now() + ROUTE_TTL_MS,
             routeHints: identity.listenAddresses,
             coordinationRelays: identity.coordinationRelays,
+            ...(this.#endpointKind ? { endpointKind: this.#endpointKind } : {}),
+            ...(stored.displayName ? { displayName: stored.displayName } : {}),
             ...(stored.transitMeshId ? { transitMeshId: stored.transitMeshId } : {}),
         });
         const proof = await this.#peer.signIdentity(peerMeshRouteRecordSigningBytes(route));
@@ -660,6 +783,9 @@ class PeerMeshNodeImpl {
                 revision: state.roster.roster.revision + 1,
                 members: next.members,
                 closed: next.closed,
+                ...(state.roster.roster.displayName
+                    ? { displayName: state.roster.roster.displayName }
+                    : {}),
             }, authorityKeys(state));
             const updated = {
                 ...state,
@@ -676,7 +802,7 @@ class PeerMeshNodeImpl {
         await this.#refreshLocalRoute();
         await this.#reconcileTransit();
         const stored = this.#store.read();
-        return peerMeshStatus(findMesh(stored.meshes, meshId), this.#peer.identity(), stored.routes);
+        return peerMeshStatus(findMesh(stored.meshes, meshId), this.#peer.identity(), this.#endpointKind, stored.routes);
     }
     #acceptIncoming(stream) {
         let peerStreams = 0;
@@ -932,7 +1058,7 @@ class PeerMeshNodeImpl {
             if (route.peerId === localPeerId ||
                 route.expiresAt <= now ||
                 route.transitMeshId === undefined ||
-                route.routeHints.length === 0) {
+                route.routeHints.length + route.coordinationRelays.length === 0) {
                 return false;
             }
             return isActiveMeshMember(stored.meshes, route.transitMeshId, localPeerId, route.peerId);
@@ -953,13 +1079,18 @@ function transitRelayCandidates(routes) {
     for (const { route } of routes) {
         if (remaining === 0)
             break;
-        const addresses = [
+        const routeHints = [
             ...new Set(route.routeHints.filter((address) => isBaseRelayFor(address, route.peerId))),
         ].slice(0, Math.min(PEER_MESH_MAX_TRANSIT_ADDRESSES_PER_RELAY, remaining));
-        if (addresses.length === 0)
+        const coordinationRelays = [...new Set(route.coordinationRelays)].slice(0, Math.min(PEER_MESH_MAX_TRANSIT_ADDRESSES_PER_RELAY - routeHints.length, remaining - routeHints.length));
+        if (routeHints.length + coordinationRelays.length === 0)
             continue;
-        candidates.push(Object.freeze({ peerId: route.peerId, addresses: Object.freeze(addresses) }));
-        remaining -= addresses.length;
+        candidates.push(Object.freeze({
+            peerId: route.peerId,
+            addresses: Object.freeze(routeHints),
+            coordinationRelays: Object.freeze(coordinationRelays),
+        }));
+        remaining -= routeHints.length + coordinationRelays.length;
     }
     return Object.freeze(candidates);
 }
@@ -976,7 +1107,9 @@ function isActiveMeshMember(meshes, meshId, localPeerId, peerId) {
         isActiveMembership(mesh, localPeerId) &&
         mesh.roster.roster.members.includes(peerId));
 }
-function peerMeshStatus(state, identity, routes = [], now = Date.now()) {
+function peerMeshStatus(state, identity, endpointKind, routes = [], now = Date.now()) {
+    const localDisplayName = routes.find(({ route }) => route.peerId === identity.peerId)?.route
+        .displayName;
     return Object.freeze({
         role: state.role === 'authority' ? 'authority' : 'member',
         authority: state.role === 'authority' ? authorityTarget(identity) : state.authority,
@@ -985,20 +1118,30 @@ function peerMeshStatus(state, identity, routes = [], now = Date.now()) {
             ? state.invitations.filter((invitation) => invitation.status === 'pending' && invitation.expiresAt > now).length
             : 0,
         memberRoutes: Object.freeze(state.roster.roster.members.map((peerId) => {
-            if (peerId === identity.peerId)
-                return Object.freeze({ peerId, state: 'local' });
+            if (peerId === identity.peerId) {
+                return Object.freeze({
+                    peerId,
+                    ...(endpointKind ? { endpointKind } : {}),
+                    ...(localDisplayName ? { displayName: localDisplayName } : {}),
+                    state: 'local',
+                });
+            }
             const route = routes.find((candidate) => candidate.route.peerId === peerId)?.route;
             if (!route)
                 return Object.freeze({ peerId, state: 'unknown' });
             if (route.expiresAt <= now) {
                 return Object.freeze({
                     peerId,
+                    ...(route.endpointKind ? { endpointKind: route.endpointKind } : {}),
+                    ...(route.displayName ? { displayName: route.displayName } : {}),
                     state: 'stale',
                     expiresAt: route.expiresAt,
                 });
             }
             return Object.freeze({
                 peerId,
+                ...(route.endpointKind ? { endpointKind: route.endpointKind } : {}),
+                ...(route.displayName ? { displayName: route.displayName } : {}),
                 state: route.routeHints.length > 0
                     ? 'route_available'
                     : 'coordination_only',
@@ -1118,6 +1261,23 @@ function responseRoutes(state, routes, knownRoutes, now) {
 function sameAddresses(left, right) {
     return left.length === right.length && left.every((address, index) => address === right[index]);
 }
+function mergeAddresses(primary, fallback) {
+    return Object.freeze([...new Set([...primary, ...fallback])].slice(0, 32));
+}
+function waitForTurn(previous, signal) {
+    if (!signal)
+        return previous;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        void previous.then(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        });
+    });
+}
 function mergeTargets(primary, fallback) {
     return Object.freeze({
         peerId: primary.peerId,

package/node_modules/@maka/runtime-host/dist/peer-mesh/owner.js

@@ -42,6 +42,7 @@ export async function openRuntimeHostPeerMeshOwner(input) {
                 : { automaticRelayDiscovery: input.automaticRelayDiscovery }),
             routeResolver: {
                 resolveRoutes: (peerId) => resolverMesh?.resolveRoutes(peerId),
+                prepareRoutes: async (peerId, signal) => resolverMesh?.prepareRoutes(peerId, signal),
             },
         });
     }
@@ -54,6 +55,7 @@ export async function openRuntimeHostPeerMeshOwner(input) {
         mesh = await openPeerMeshNode({
             dataRoot: join(input.dataRoot, client.identity().peerId),
             peer: client,
+            endpointKind: input.endpointKind,
         });
         resolverMesh = mesh;
     }

package/node_modules/@maka/runtime-host/dist/peer-mesh/store.js

@@ -20,6 +20,7 @@ import { chmod, lstat, mkdir, open, readFile, rename, unlink } from 'node:fs/pro
 import { dirname, join } from 'node:path';
 import { acquireFileLifetimeOwner, } from '@maka/storage/file-lifetime-owner';
 import { decodeAuthorityTarget, decodeSignedPeerMeshRoster, decodeSignedPeerMeshRouteRecord, PEER_MESH_MAX_INVITATION_RECORDS, PEER_MESH_MAX_MEMBERS, PEER_MESH_MAX_MESHES, PEER_MESH_MAX_PENDING_INVITATIONS, validatePeerMeshAuthorityKeyPair, } from './model.js';
+import { canonicalPeerMeshDisplayName } from './display-name.js';
 const STATE_FILE = 'peer-mesh.json';
 const LOCK_FILE = 'peer-mesh.owner';
 const MAX_STATE_BYTES = 1024 * 1024;
@@ -94,7 +95,7 @@ class PeerMeshStateStoreImpl {
         const task = this.#tail.then(async () => {
             if (this.#failure)
                 throw this.#failure;
-            const updated = operation(this.#state);
+            const updated = await operation(this.#state);
             if (updated.state === this.#state)
                 return updated.result;
             const candidate = pruneUnreferencedRoutes(updated.state, this.localPeerId);
@@ -251,21 +252,30 @@ async function readState(path, expectedLocalPeerId) {
             Object.hasOwn(record, 'meshes') &&
             Object.hasOwn(record, 'routes') &&
             Object.hasOwn(record, 'transitMeshId');
-        if (!versionOne && !versionTwo && !versionThree) {
+        const versionFour = record.version === 4 &&
+            Object.keys(record).length === 6 &&
+            Object.hasOwn(record, 'localPeerId') &&
+            Object.hasOwn(record, 'displayName') &&
+            Object.hasOwn(record, 'meshes') &&
+            Object.hasOwn(record, 'routes') &&
+            Object.hasOwn(record, 'transitMeshId');
+        if (!versionOne && !versionTwo && !versionThree && !versionFour) {
             throw new Error('Unsupported Peer Mesh state document');
         }
         if (boundedString(record.localPeerId, 'localPeerId', 256) !== expectedLocalPeerId) {
             throw new Error('Peer Mesh state belongs to a different peer identity');
         }
         return decodePeerMeshStoredState({
+            displayName: versionFour ? record.displayName : null,
             meshes: record.meshes,
             routes: versionOne ? [] : record.routes,
-            transitMeshId: versionThree ? record.transitMeshId : null,
+            transitMeshId: versionThree || versionFour ? record.transitMeshId : null,
         }, expectedLocalPeerId);
     }
     catch (error) {
         if (isNodeError(error, 'ENOENT')) {
             return Object.freeze({
+                displayName: null,
                 meshes: Object.freeze([]),
                 routes: Object.freeze([]),
                 transitMeshId: null,
@@ -286,7 +296,7 @@ async function pathExists(path) {
     }
 }
 async function writeState(path, localPeerId, state) {
-    const document = `${JSON.stringify({ version: 3, localPeerId, ...state }, null, 2)}\n`;
+    const document = `${JSON.stringify({ version: 4, localPeerId, ...state }, null, 2)}\n`;
     if (Buffer.byteLength(document) > MAX_STATE_BYTES)
         throw new Error('Peer Mesh state is too large');
     const temporary = `${path}.tmp`;
@@ -395,13 +405,15 @@ function decodePeerMeshStoredState(value, localPeerId) {
         throw new Error('Invalid Peer Mesh state document');
     }
     const record = value;
-    if (Object.keys(record).length !== 3 ||
+    if (Object.keys(record).length !== 4 ||
+        !Object.hasOwn(record, 'displayName') ||
         !Object.hasOwn(record, 'meshes') ||
         !Object.hasOwn(record, 'routes') ||
         !Object.hasOwn(record, 'transitMeshId')) {
         throw new Error('Invalid Peer Mesh state document');
     }
     const meshes = decodePeerMeshStates(record.meshes, localPeerId);
+    const displayName = record.displayName === null ? null : canonicalPeerMeshDisplayName(record.displayName);
     const transitMeshId = record.transitMeshId === null
         ? null
         : boundedString(record.transitMeshId, 'transitMeshId', 128);
@@ -410,6 +422,7 @@ function decodePeerMeshStoredState(value, localPeerId) {
         throw new Error('Peer Mesh transit selection is not an active membership');
     }
     return Object.freeze({
+        displayName,
         meshes,
         routes: decodeRoutes(record.routes, meshes),
         transitMeshId,

package/node_modules/@maka/runtime-host/dist/protocol/index.js

@@ -59,7 +59,11 @@ export const RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION = 1;
 export const RUNTIME_HOST_PROTOCOL_VERSION = 0;
 // Increment when the same protocol version no longer guarantees safe Client-Host
 // interoperability. Mismatches are rejected before domain commands are admitted.
-export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 74;
+export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 76;
+// 76: Peer Mesh endpoint and Mesh display names are signed, persisted facts
+// managed through Host operations rather than local-only Client labels.
+// 75: Peer Mesh routes identify whether a peer is a Client or Runtime Host so
+// management surfaces can present the endpoint authority boundary accurately.
 // 74: Capability-provider credentials may carry one Host-authenticated owner
 // identity. Older peers cannot preserve the association and could select an
 // unrelated provider for an interactive Session.