@twinsearth/w2m-dsh-plugin 0.5.7 → 0.5.9

package/src/agent/mdns-wire.mjs

@@ -1,10 +1,10 @@
 /**
- * Multicast DNS wire codec 鈥?a bounded, hand-written DNS message encoder and decoder.
+ * Multicast DNS wire codec --a bounded, hand-written DNS message encoder and decoder.
  *
  * # THE RULE
  *
  * **Discovery is a hint, never an authorisation.** A discovered device is a *candidate to ask*. It
- * never skips, weakens or short-circuits any existing gate 鈥?the device token, the per-machine
+ * never skips, weakens or short-circuits any existing gate --the device token, the per-machine
  * allow-list, the git anchors, the verdict model. Nothing in this file, in `src/agent/mdns.mjs`, or in
  * `src/plugin/mdns-discover.mjs` may treat "we saw it announce itself" as "we may run there". If a
  * future edit finds itself writing code where a discovered device is trusted *because it was
@@ -14,10 +14,10 @@
  *
  * # Clean room
  *
- * Written from the published rules 鈥?RFC 1035 搂4.1 (message format, name compression), RFC 1035
- * 搂2.3.4 (the 255-octet name limit), RFC 1035 搂3.1/搂3.2.2 (record and type definitions), RFC 2782
- * (SRV), RFC 6763 (DNS-SD record layout, the TXT record's key=value convention), RFC 6762 搂18
- * (mDNS message format) and RFC 6762 搂10 (TTL values, goodbye packets). No third-party
+ * Written from the published rules --RFC 1035 --4.1 (message format, name compression), RFC 1035
+ * --2.3.4 (the 255-octet name limit), RFC 1035 --3.1/--3.2.2 (record and type definitions), RFC 2782
+ * (SRV), RFC 6763 (DNS-SD record layout, the TXT record's key=value convention), RFC 6762 --18
+ * (mDNS message format) and RFC 6762 --10 (TTL values, goodbye packets). No third-party
  * implementation was consulted line by line and none was copied: this project is MIT and stays free of
  * third-party notice entanglement, and deriving from the specification is also what lets us *not*
  * reproduce the defects a studied implementation had.
@@ -31,7 +31,7 @@
  *     scan must be seen at its new address, not at the address it had when the scan began.
  *   * **a name as identity.** Nothing here decides identity at all; the codec only reports what the
  *     wire said, including the exact `name` bytes as written. Identity is decided in
- *     `src/plugin/mdns-discover.mjs`, by a `machine_id` the relay assigned 鈥?never by a matching
+ *     `src/plugin/mdns-discover.mjs`, by a `machine_id` the relay assigned --never by a matching
  *     service or host name.
  *
  * # What is implemented, and what is not
@@ -52,17 +52,17 @@
  *   | guard                        | limit | refusal              |
  *   | ---------------------------- | ----- | -------------------- |
  *   | label length octet           | 63    | `MDNS_LABEL_TOO_LONG`|
- *   | unsupported label kind (01/10)| 鈥?   | `MDNS_LABEL_TYPE`    |
+ *   | unsupported label kind (01/10)| --   | `MDNS_LABEL_TYPE`    |
  *   | expanded name length         | 255   | `MDNS_NAME_TOO_LONG` |
  *   | compression pointer target   | must be strictly earlier in the message | `MDNS_POINTER_LOOP` |
  *   | compression pointer hops     | 128   | `MDNS_POINTER_HOPS`  |
  *   | records per message          | 256   | `MDNS_RECORD_COUNT`  |
  *   | message size                 | 9000  | `MDNS_MESSAGE_TOO_LARGE` |
- *   | any read past the end        | 鈥?    | `MDNS_TRUNCATED`     |
+ *   | any read past the end        | --    | `MDNS_TRUNCATED`     |
  *
  * The two pointer guards are both load-bearing, and neither is decoration:
  *
- *   * RFC 1035 搂4.1.4 says a pointer refers to "a prior occurrence" of the name, i.e. to an offset
+ *   * RFC 1035 --4.1.4 says a pointer refers to "a prior occurrence" of the name, i.e. to an offset
  *     *earlier* in the message. A pointer that does not point strictly backwards is the only way to
  *     build a cycle, so it is refused as a loop. This alone guarantees termination.
  *   * The hop counter (128, the conventional guard) is the bound on *work*, not just on loops: a
@@ -79,13 +79,13 @@ import { Buffer } from 'node:buffer';
 // Constants
 // ---------------------------------------------------------------------------------------------
 
-/** DNS CLASS IN (RFC 1035 搂3.2.4). */
+/** DNS CLASS IN (RFC 1035 --3.2.4). */
 export const DNS_CLASS_IN = 1;
 
-/** DNS CLASS ANY (`*`), which mDNS queries use to ask for every type of a name (RFC 6762 搂5). */
+/** DNS CLASS ANY (`*`), which mDNS queries use to ask for every type of a name (RFC 6762 --5). */
 export const DNS_CLASS_ANY = 255;
 
-/** Record types this layer reads. RFC 1035 搂3.2.2, RFC 1035 搂3.2.3 (AAAA is RFC 3596), RFC 2782. */
+/** Record types this layer reads. RFC 1035 --3.2.2, RFC 1035 --3.2.3 (AAAA is RFC 3596), RFC 2782. */
 export const RECORD_TYPE = Object.freeze({
   A: 1,
   PTR: 12,
@@ -108,26 +108,26 @@ const TYPE_NAME = Object.freeze({
 /**
  * The most significant bit of the *rrclass* field in a response record.
  *
- * RFC 6762 搂10.2: "this is not a record class 0x8001" 鈥?the bit means "the rest of this RRset is
+ * RFC 6762 --10.2: "this is not a record class 0x8001" --the bit means "the rest of this RRset is
  * replaced", and it must be masked off before the class is compared. It is the *same bit value* as
  * {@link UNICAST_RESPONSE} in a question, but a different field with a different meaning; the two
  * constants are separate so a future edit cannot conflate them.
  */
 export const CACHE_FLUSH = 0x8000;
 
-/** The most significant bit of the *qclass* field in a question (RFC 6762 搂5.4, "QU" questions). */
+/** The most significant bit of the *qclass* field in a question (RFC 6762 --5.4, "QU" questions). */
 export const UNICAST_RESPONSE = 0x8000;
 
-/** RFC 1035 搂2.3.4: a label is at most 63 octets, which is why the top two bits can be flags. */
+/** RFC 1035 --2.3.4: a label is at most 63 octets, which is why the top two bits can be flags. */
 export const MAX_LABEL_BYTES = 63;
 
-/** RFC 1035 搂2.3.4: a name (length octets, label octets and the terminating zero) is at most 255. */
+/** RFC 1035 --2.3.4: a name (length octets, label octets and the terminating zero) is at most 255. */
 export const MAX_NAME_BYTES = 255;
 
 /**
  * Largest message this codec will parse or produce.
  *
- * RFC 6762 搂17 asks that multicast messages fit in 1500 bytes "whenever possible" and caps them at
+ * RFC 6762 --17 asks that multicast messages fit in 1500 bytes "whenever possible" and caps them at
  * 9000 (`MAX_MESSAGE_BYTES` here). The cap is also a bound on parser work, which is the reason it is
  * enforced on *decode* as well: a datagram larger than this is refused before a single name is read.
  */
@@ -143,8 +143,8 @@ export const MAX_RECORDS = 256;
 export const MAX_COMPRESSION_ENTRIES = 512;
 
 /**
- * The two top bits of a length octet (RFC 1035 搂4.1.4): `00` is a label length, `11` is a compression
- * pointer, `01` and `10` are reserved. The mask is one octet wide 鈥?the 16-bit form, `0xc000`, is what
+ * The two top bits of a length octet (RFC 1035 --4.1.4): `00` is a label length, `11` is a compression
+ * pointer, `01` and `10` are reserved. The mask is one octet wide --the 16-bit form, `0xc000`, is what
  * the *writer* ORs into a pointer, and mixing the two up makes every pointer unreadable.
  */
 const LABEL_KIND_MASK = 0xc0;
@@ -153,8 +153,8 @@ const LABEL_KIND_MASK = 0xc0;
 const POINTER_WORD_MASK = 0xc000;
 
 /**
- * RFC 6762 搂6.7: a response to a query from a source port other than 5353 is a *legacy* unicast
- * response, and its TTLs "SHOULD NOT be greater than ten seconds" 鈥?the resolver that asked has no
+ * RFC 6762 --6.7: a response to a query from a source port other than 5353 is a *legacy* unicast
+ * response, and its TTLs "SHOULD NOT be greater than ten seconds" --the resolver that asked has no
  * cache-coherency protocol and would keep the record long after it stopped being true.
  */
 export const LEGACY_UNICAST_TTL = 10;
@@ -162,10 +162,10 @@ export const LEGACY_UNICAST_TTL = 10;
 /** 14 bits of pointer target, i.e. the largest offset a pointer can name. */
 const MAX_POINTER_TARGET = 0x3fff;
 
-/** Header size: ID, flags, and four section counts (RFC 1035 搂4.1.1). */
+/** Header size: ID, flags, and four section counts (RFC 1035 --4.1.1). */
 const HEADER_BYTES = 12;
 
-/** Flag bits of the second header word (RFC 1035 搂4.1.1). */
+/** Flag bits of the second header word (RFC 1035 --4.1.1). */
 export const FLAG = Object.freeze({
   QR: 0x8000,
   AA: 0x0400,
@@ -198,7 +198,7 @@ export const REFUSAL = Object.freeze({
 /**
  * An invalid *argument* to an encoder.
  *
- * The decoder never throws 鈥?it refuses. The encoder does, because its input is our own data: writing
+ * The decoder never throws --it refuses. The encoder does, because its input is our own data: writing
  * a packet we know to be malformed would put a lie on the wire where nobody is left to catch it.
  */
 export class MdnsWireError extends Error {
@@ -225,7 +225,7 @@ function refuse(reason, detail = undefined) {
 /**
  * Lower-case a name and drop one trailing dot, for case-insensitive comparison.
  *
- * DNS names are case-insensitive (RFC 1035 搂2.3.3) but the wire case is preserved everywhere else in
+ * DNS names are case-insensitive (RFC 1035 --2.3.3) but the wire case is preserved everywhere else in
  * this module, because a DNS-SD *instance* name is a human-readable label and "Mac Studio" is not
  * "mac studio" to the person who reads it.
  *
@@ -282,7 +282,7 @@ export function splitName(name, what = 'name') {
     if (bytes > MAX_LABEL_BYTES) {
       throw new MdnsWireError(
         REFUSAL.LABEL_TOO_LONG,
-        `${what} ${JSON.stringify(name)} has a ${bytes}-octet label; RFC 1035 搂2.3.4 allows ${MAX_LABEL_BYTES}`,
+        `${what} ${JSON.stringify(name)} has a ${bytes}-octet label; RFC 1035 --2.3.4 allows ${MAX_LABEL_BYTES}`,
       );
     }
     encoded += bytes + 1;
@@ -290,14 +290,14 @@ export function splitName(name, what = 'name') {
   if (encoded > MAX_NAME_BYTES) {
     throw new MdnsWireError(
       REFUSAL.NAME_TOO_LONG,
-      `${what} ${JSON.stringify(name)} encodes to ${encoded} octets; RFC 1035 搂2.3.4 allows ${MAX_NAME_BYTES}`,
+      `${what} ${JSON.stringify(name)} encodes to ${encoded} octets; RFC 1035 --2.3.4 allows ${MAX_NAME_BYTES}`,
     );
   }
   return labels;
 }
 
 /**
- * `a.b.c.` 鈫?encoded name, with no compression (a standalone helper for tests and for RDATA that must
+ * `a.b.c.` --?encoded name, with no compression (a standalone helper for tests and for RDATA that must
  * not be compressed).
  *
  * @param {string} name
@@ -315,7 +315,7 @@ export function encodeName(name, options = {}) {
   return Buffer.concat(parts);
 }
 
-/** `192.168.0.1` 鈫?4 octets. Strict: four decimal octets, each 0-255, no shorthand. */
+/** `192.168.0.1` --?4 octets. Strict: four decimal octets, each 0-255, no shorthand. */
 export function parseIpv4(text) {
   if (typeof text !== 'string')
     throw new MdnsWireError('MDNS_A_INVALID', `IPv4 address must be a string, got ${typeof text}`);
@@ -334,13 +334,13 @@ export function parseIpv4(text) {
   return bytes;
 }
 
-/** 4 octets 鈫?dotted quad. */
+/** 4 octets --?dotted quad. */
 export function formatIpv4(bytes) {
   return `${bytes[0]}.${bytes[1]}.${bytes[2]}.${bytes[3]}`;
 }
 
 /**
- * `2001:db8::1` 鈫?16 octets, with `::` expansion and an embedded IPv4 tail.
+ * `2001:db8::1` --?16 octets, with `::` expansion and an embedded IPv4 tail.
  *
  * Hand-written rather than borrowed: `node:net` validates an IPv6 literal but does not hand back its
  * bytes, and the only other source of bytes would be a dependency this project does not take.
@@ -359,7 +359,7 @@ export function parseIpv6(text) {
   if (value.includes('%'))
     throw new MdnsWireError('MDNS_AAAA_INVALID', `${text} carries a zone index, which is link-local only`);
   if (value.includes('.')) {
-    // An embedded IPv4 tail (RFC 4291 搂2.2): convert it to two groups and re-parse.
+    // An embedded IPv4 tail (RFC 4291 --2.2): convert it to two groups and re-parse.
     const cut = value.lastIndexOf(':');
     if (cut === -1)
       throw new MdnsWireError('MDNS_AAAA_INVALID', `${text} has an IPv4 tail but no IPv6 prefix`);
@@ -395,7 +395,7 @@ export function parseIpv6(text) {
 }
 
 /**
- * 16 octets 鈫?text, with the longest run of zero groups collapsed to `::` (RFC 5952 搂4.2).
+ * 16 octets --?text, with the longest run of zero groups collapsed to `::` (RFC 5952 --4.2).
  *
  * @param {Buffer} bytes
  * @returns {string}
@@ -458,7 +458,7 @@ function readName(buffer, start) {
   /** Offset just past the name in the *original* stream, which a pointer fixes once and for all. */
   let next = null;
   let hops = 0;
-  let expanded = 1; // the terminating zero octet counts towards the 255 (RFC 1035 搂2.3.4)
+  let expanded = 1; // the terminating zero octet counts towards the 255 (RFC 1035 --2.3.4)
 
   for (;;) {
     if (position >= buffer.length) return refuse(REFUSAL.TRUNCATED, { at: position, reading: 'name' });
@@ -473,7 +473,7 @@ function readName(buffer, start) {
       // is refused as a budget overrun rather than being mistaken for a loop.
       if (hops >= MAX_POINTER_HOPS)
         return refuse(REFUSAL.POINTER_HOPS, { hops, target, limit: MAX_POINTER_HOPS });
-      // RFC 1035 搂4.1.4: a pointer names a *prior* occurrence. A pointer that does not go strictly
+      // RFC 1035 --4.1.4: a pointer names a *prior* occurrence. A pointer that does not go strictly
       // backwards is the only way to build a cycle, so it is refused as one. This is what makes
       // termination a property of the format rather than of the hop counter.
       if (target >= position) return refuse(REFUSAL.POINTER_LOOP, { target, position });
@@ -482,7 +482,7 @@ function readName(buffer, start) {
       continue;
     }
 
-    // `01` and `10` are reserved label kinds (RFC 1035 搂4.1.4 defines only `00` and `11`). A packet
+    // `01` and `10` are reserved label kinds (RFC 1035 --4.1.4 defines only `00` and `11`). A packet
     // using them is not something to guess at.
     if ((lengthByte & LABEL_KIND_MASK) !== 0)
       return refuse(REFUSAL.LABEL_TYPE, { octet: lengthByte, at: position });
@@ -535,7 +535,7 @@ function readRdata(buffer, rdataStart, rdataEnd, type) {
     if (length === 0) return refuse(REFUSAL.RDATA_LENGTH, { type: 'PTR', length, expected: 'a name' });
     const name = readName(buffer, rdataStart);
     if (!name.ok) return name;
-    // RFC 1035 搂4.1.4 permits PTR RDATA to be compressed, and mDNS implementations do it, so a
+    // RFC 1035 --4.1.4 permits PTR RDATA to be compressed, and mDNS implementations do it, so a
     // pointer is followed here (leniently) even though the encoder writes this name uncompressed.
     return { ok: true, value: { target: name.name } };
   }
@@ -611,11 +611,11 @@ function readRecord(buffer, offset, section, context) {
       name: name.name,
       type,
       type_name: typeName(type),
-      // RFC 6762 搂10.2: the cache-flush bit is not part of the class and must be masked off.
+      // RFC 6762 --10.2: the cache-flush bit is not part of the class and must be masked off.
       class: rrclass & 0x7fff,
       cache_flush: (rrclass & CACHE_FLUSH) !== 0,
       ttl,
-      // TTL 0 is a goodbye (RFC 6762 搂10.1), and it is a *value*, not an error: the consumers drop
+      // TTL 0 is a goodbye (RFC 6762 --10.1), and it is a *value*, not an error: the consumers drop
       // the record when they see it.
       goodbye: ttl === 0,
       rdata: Buffer.from(buffer.subarray(rdataStart, rdataEnd)),
@@ -666,7 +666,7 @@ export function decodeMessage(buffer) {
         name: name.name,
         type: buffer.readUInt16BE(offset),
         class: qclass & 0x7fff,
-        // RFC 6762 搂5.4: the top bit of the class asks for a unicast reply ("QU").
+        // RFC 6762 --5.4: the top bit of the class asks for a unicast reply ("QU").
         unicast_response: (qclass & UNICAST_RESPONSE) !== 0,
       });
       offset += 4;
@@ -821,9 +821,9 @@ function createWriter() {
  *
  * Compression policy, and the reasoning behind it:
  *
- *   * **PTR RDATA is compressed.** It is a name, RFC 1035 搂4.1.4 permits it, and every mDNS responder
- *     on a real LAN does it 鈥?a response that did not would be larger than the peers' own.
- *   * **SRV RDATA is not compressed.** RFC 1035 搂4.1.4 lists the types whose RDATA may be compressed
+ *   * **PTR RDATA is compressed.** It is a name, RFC 1035 --4.1.4 permits it, and every mDNS responder
+ *     on a real LAN does it --a response that did not would be larger than the peers' own.
+ *   * **SRV RDATA is not compressed.** RFC 1035 --4.1.4 lists the types whose RDATA may be compressed
  *     and SRV (RFC 2782) is not among them, which is the conservative reading every interoperating
  *     implementation follows. The *decoder* still follows a pointer there, because refusing a packet a
  *     peer legitimately built is worse than accepting one written in a style we would not choose.
@@ -863,7 +863,7 @@ function encodeRdata(writer, record) {
  * Encode a TXT RDATA: a sequence of length-prefixed character-strings, each at most 255 octets.
  *
  * An empty list is written as one zero-length string, which is the DNS-SD convention for "this service
- * has no attributes but does have a TXT record" (RFC 6763 搂6.1).
+ * has no attributes but does have a TXT record" (RFC 6763 --6.1).
  *
  * @param {object} record
  * @returns {Buffer}
@@ -876,7 +876,7 @@ function encodeTxt(record) {
     if (bytes.length > 255)
       throw new MdnsWireError(
         'MDNS_TXT_TOO_LONG',
-        `TXT string of ${bytes.length} octets; RFC 1035 搂3.3.14 allows 255`,
+        `TXT string of ${bytes.length} octets; RFC 1035 --3.3.14 allows 255`,
       );
     parts.push(Buffer.from([bytes.length]), bytes);
   }
@@ -924,7 +924,7 @@ function writeRecord(writer, record, section) {
   writer.writeUint16(rrclass | (record.cache_flush === true || record.cacheFlush === true ? CACHE_FLUSH : 0));
   writer.writeUint32(ttl);
   // The length has to precede the RDATA, but a compressed name inside the RDATA needs the offsets of
-  // everything before it 鈥?so the RDATA is written into the message and the placeholder patched after.
+  // everything before it --so the RDATA is written into the message and the placeholder patched after.
   const placeholder = writer.reserveUint16();
   const before = writer.length;
   const rdata = encodeRdata(writer, { ...record, type });
@@ -984,9 +984,9 @@ export function encodeMessage(message = {}) {
 /**
  * Build a service-discovery query.
  *
- * RFC 6762 搂5.1: a one-shot query MUST NOT be sent from source port 5353, because that port signals a
+ * RFC 6762 --5.1: a one-shot query MUST NOT be sent from source port 5353, because that port signals a
  * fully compliant querier. The caller owns the socket and therefore the source port; this function
- * only writes the message. RFC 6762 搂18.1: the ID of a multicast query is zero.
+ * only writes the message. RFC 6762 --18.1: the ID of a multicast query is zero.
  *
  * @param {{serviceType: string, type?: number, unicastResponse?: boolean, id?: number}} options
  * @returns {Buffer}
@@ -995,7 +995,7 @@ export function encodeQuery(options) {
   const type = options.type ?? RECORD_TYPE.PTR;
   return encodeMessage({
     id: Number.isInteger(options.id) ? options.id : 0,
-    // 搂18.3/搂18.4/搂18.5/搂18.6: opcode 0, and the RD/RA/Z bits clear on transmission.
+    // --18.3/--18.4/--18.5/--18.6: opcode 0, and the RD/RA/Z bits clear on transmission.
     flags: { qr: false, opcode: 0, aa: false, tc: false, rd: false, ra: false, rcode: 0 },
     questions: [
       {
@@ -1011,7 +1011,7 @@ export function encodeQuery(options) {
 /**
  * Build a response to a question, copying the question section.
  *
- * RFC 6762 搂6.7: a response to a query from a source port other than 5353 ("legacy") MUST repeat the
+ * RFC 6762 --6.7: a response to a query from a source port other than 5353 ("legacy") MUST repeat the
  * query ID and the question. `legacy` therefore carries those two behaviours and the 10-second TTL cap
  * (see {@link capLegacyTtl}).
  *
@@ -1027,7 +1027,7 @@ export function encodeResponse(options) {
   const legacy = options.legacy === true;
   return encodeMessage({
     id: legacy && Number.isInteger(query?.id) ? query.id : 0,
-    // 搂18.7: the AA bit is set on responses; there is no recursion and no error code in mDNS.
+    // --18.7: the AA bit is set on responses; there is no recursion and no error code in mDNS.
     flags: { qr: true, opcode: 0, aa: true, tc: false, rd: false, ra: false, rcode: 0 },
     questions:
       legacy && Array.isArray(query?.questions)
@@ -1035,13 +1035,13 @@ export function encodeResponse(options) {
         : [],
     answers: answers.map((record) => withTtl(record, legacy)),
     // The additional section carries the records a peer needs next (SRV and TXT for a PTR answer, the
-    // A record for an SRV answer). 搂10.2's cache-flush bit is *not* set for a legacy unicast response.
+    // A record for an SRV answer). --10.2's cache-flush bit is *not* set for a legacy unicast response.
     additionals: additionals.map((record) => withTtl(record, legacy)),
   });
 }
 
 /**
- * Apply RFC 6762 搂6.7's TTL cap and cache-flush rule to one record of a response.
+ * Apply RFC 6762 --6.7's TTL cap and cache-flush rule to one record of a response.
  *
  * A legacy resolver is a plain DNS client with no cache-coherency protocol, so it must not be handed a
  * 75-minute TTL: "the resource record TTL given in a legacy unicast response SHOULD NOT be greater

package/src/agent/mdns.mjs

@@ -19,34 +19,34 @@
  * # Clean room
  *
  * Written from RFC 6762 (Multicast DNS), RFC 6763 (DNS-Based Service Discovery), RFC 2782 (SRV) and
- * RFC 1035 §4.1 (message format). See `src/agent/mdns-wire.mjs` for the two studied-implementation
+ * RFC 1035 sec.4.1 (message format). See `src/agent/mdns-wire.mjs` for the two studied-implementation
  * behaviours this layer deliberately does *not* reproduce (first-writer-wins record updates, and a name
  * treated as identity).
  *
  * # What this implements, exactly
  *
  *   * `buildServiceRecords` — the four records a W2M service instance publishes: a shared PTR under
- *     `_w2m._tcp.local`, and unique SRV + TXT + A records. TTLs follow RFC 6762 §10: 120 s for records
+ *     `_w2m._tcp.local`, and unique SRV + TXT + A records. TTLs follow RFC 6762 sec.10: 120 s for records
  *     naming or containing a host name (SRV, A), 75 minutes for the others (PTR, TXT).
  *   * `createResponder` — announces on start, answers matching questions, re-announces on a timer, and
- *     sends a TTL=0 goodbye on close (RFC 6762 §10.1) so peers drop us immediately instead of waiting
+ *     sends a TTL=0 goodbye on close (RFC 6762 sec.10.1) so peers drop us immediately instead of waiting
  *     out a 75-minute TTL.
- *   * `discoverServices` — one bounded scan with a fresh socket per call, which is what RFC 6762 §5.1
- *     describes ("one-shot" queries from an ephemeral source port; §5.1 is also why the socket is
+ *   * `discoverServices` — one bounded scan with a fresh socket per call, which is what RFC 6762 sec.5.1
+ *     describes ("one-shot" queries from an ephemeral source port; sec.5.1 is also why the socket is
  *     never bound to 5353).
  *
  * # Scope, stated rather than glossed
  *
  *   * **IPv4 only.** `224.0.0.251` and the `udp4` socket family. IPv6 (`ff02::fb`) is not half-built
  *     here; it would need its own socket, its own interface enumeration and its own tests.
- *   * **No probing or conflict resolution** (RFC 6762 §8.1, §9). A responder here announces its
+ *   * **No probing or conflict resolution** (RFC 6762 sec.8.1, sec.9). A responder here announces its
  *     records immediately and does not defend them. Two machines configured with the same instance
  *     name would both answer. That is a real limitation, and it is acceptable *only* because of the
  *     rule above: a discovered name is a hint, and the pairing that actually authorises anything is
  *     keyed by machine id, not by the name two machines might collide on.
- *   * **No known-answer suppression** (RFC 6762 §7.1) and no negative responses (NSEC). A scan is one
+ *   * **No known-answer suppression** (RFC 6762 sec.7.1) and no negative responses (NSEC). A scan is one
  *     query; nothing here is a long-lived browsing client.
- *   * **The 10-second re-announce is a deliberate deviation.** RFC 6762 §8.3 says a responder "MUST NOT
+ *   * **The 10-second re-announce is a deliberate deviation.** RFC 6762 sec.8.3 says a responder "MUST NOT
  *     send regular periodic announcements as a matter of course" and asks for at least two
  *     announcements one second apart with the interval doubling. The periodic re-announce exists here
  *     because this is a small, fixed set of records on a tool that expects peers to appear and vanish,
@@ -71,31 +71,31 @@ import {
   normalizeName,
 } from './mdns-wire.mjs';
 
-/** The IPv4 link-local multicast address every mDNS name resolves through (RFC 6762 §3). */
+/** The IPv4 link-local multicast address every mDNS name resolves through (RFC 6762 sec.3). */
 export const MDNS_GROUP = '224.0.0.251';
 
-/** The mDNS UDP port (RFC 6762 §5). A source port of 5353 means "fully compliant querier". */
+/** The mDNS UDP port (RFC 6762 sec.5). A source port of 5353 means "fully compliant querier". */
 export const MDNS_PORT = 5353;
 
 /** The service type W2M instances advertise under. */
 export const DEFAULT_SERVICE_TYPE = '_w2m._tcp.local';
 
-/** Default window for one scan. RFC 6762 §5.2 expects responses within about a second. */
+/** Default window for one scan. RFC 6762 sec.5.2 expects responses within about a second. */
 export const DEFAULT_DISCOVERY_TIMEOUT_MS = 1500;
 
-/** Default re-announce period. See the header: this is a deliberate deviation from RFC 6762 §8.3. */
+/** Default re-announce period. See the header: this is a deliberate deviation from RFC 6762 sec.8.3. */
 export const DEFAULT_ANNOUNCE_INTERVAL_MS = 10_000;
 
-/** RFC 6762 §10: 120 s where a host name is involved, 75 minutes (4500 s) for everything else. */
+/** RFC 6762 sec.10: 120 s where a host name is involved, 75 minutes (4500 s) for everything else. */
 export const DEFAULT_TTL_SECONDS = Object.freeze({ ptr: 4500, srv: 120, txt: 4500, address: 120 });
 
-/** RFC 6762 §10.1: a goodbye is the same record with an RR TTL of zero. */
+/** RFC 6762 sec.10.1: a goodbye is the same record with an RR TTL of zero. */
 export const GOODBYE_TTL = 0;
 
 /** Upper bound on instances one scan will report, so a flooding peer cannot grow this without limit. */
 export const MAX_SCAN_INSTANCES = 64;
 
-/** The first TXT string DNS-SD asks for (RFC 6763 §6.1). */
+/** The first TXT string DNS-SD asks for (RFC 6763 sec.6.1). */
 export const TXT_VERSION = 'txtvers=1';
 
 /** TXT keys this layer reads. `mid` is the *only* one that can carry identity, and it is the relay's. */
@@ -195,7 +195,7 @@ export function localHostLabel(hostname = os.hostname()) {
 /**
  * The records one W2M service instance publishes.
  *
- * Layout follows DNS-SD (RFC 6763 §4–§6) with W2M's own keys in the TXT record:
+ * Layout follows DNS-SD (RFC 6763 sec.4–sec.6) with W2M's own keys in the TXT record:
  *
  *   `_w2m._tcp.local` PTR → `<instance>._w2m._tcp.local`            shared,   TTL 4500
  *   `<instance>._w2m._tcp.local` SRV → `<host>.local` port          unique,   TTL 120
@@ -217,7 +217,7 @@ export function localHostLabel(hostname = os.hostname()) {
  * @param {string|null} [options.machineId] The relay's machine id, published as `mid=`.
  * @param {string|null} [options.machineName] Display name, published as `name=`.
  * @param {object} [options.ttl] Overrides for {@link DEFAULT_TTL_SECONDS}.
- * @param {boolean} [options.goodbye] Emit the same records with TTL 0 (RFC 6762 §10.1).
+ * @param {boolean} [options.goodbye] Emit the same records with TTL 0 (RFC 6762 sec.10.1).
  * @returns {object[]}
  */
 export function buildServiceRecords(options) {
@@ -250,7 +250,7 @@ export function buildServiceRecords(options) {
     // Shared: many responders may publish a PTR for the same service type, so no cache-flush bit.
     { name: serviceType, type: RECORD_TYPE.PTR, ttl: at(ttl.ptr), target: instanceFqdn },
     // Unique: exactly one owner, so the cache-flush bit tells peers to drop older SRV/TXT/A records
-    // for these names (RFC 6762 §10.2). This is what stops a peer that moved from keeping the old
+    // for these names (RFC 6762 sec.10.2). This is what stops a peer that moved from keeping the old
     // address: the new record *replaces* rather than joins.
     {
       name: instanceFqdn,
@@ -273,7 +273,7 @@ export function buildServiceRecords(options) {
       cache_flush: !goodbye,
     });
   }
-  // A goodbye is a *deletion*. RFC 6762 §10.1 has the TTL alone carry that meaning, and §10.2's
+  // A goodbye is a *deletion*. RFC 6762 sec.10.1 has the TTL alone carry that meaning, and sec.10.2's
   // cache-flush bit must not be set on it: a cooperating responder's own records for the same name
   // must not be flushed along with ours.
   return goodbye ? records.map((record) => ({ ...record, cache_flush: false })) : records;
@@ -290,13 +290,13 @@ export function buildServiceRecords(options) {
  * studied implementation has: **there is no first-writer-wins and no "keep the first non-zero port".**
  *
  *   * A record is identified by `(name, type, rdata)`. A later copy of the same record *replaces* the
- *     earlier one and restarts its TTL — the definition of a cache update (RFC 1035 §3.2.1, RFC 6762
- *     §10).
+ *     earlier one and restarts its TTL — the definition of a cache update (RFC 1035 sec.3.2.1, RFC 6762
+ *     sec.10).
  *   * A record carrying the cache-flush bit replaces the whole RRset of that `(name, type)`: other
- *     RDATA for the same name and type is dropped. RFC 6762 §10.2 gives other members one second of
+ *     RDATA for the same name and type is dropped. RFC 6762 sec.10.2 gives other members one second of
  *     grace for the multi-packet case; this cache has no second consumer and no peer reading it, so it
  *     drops them immediately, which is the *safe* direction — a stale address never survives.
- *   * A record with TTL 0 is a goodbye (RFC 6762 §10.1) and deletes every record with that
+ *   * A record with TTL 0 is a goodbye (RFC 6762 sec.10.1) and deletes every record with that
  *     `(name, type)` at once. RFC 6762 suggests a long-lived querier record TTL 1 and delete a second
  *     later, to give cooperating responders a chance to rescue the records; for a bounded scan the
  *     honest reading is "the peer said this is gone", and keeping it for a second would mean reporting
@@ -539,7 +539,7 @@ export function parseServiceInstances(input, options = {}) {
 /**
  * TXT character-strings → a key/value map.
  *
- * RFC 6763 §6.1: a string with no `=` is a key with an empty value; a duplicate key keeps the first
+ * RFC 6763 sec.6.1: a string with no `=` is a key with an empty value; a duplicate key keeps the first
  * occurrence (the RFC's rule for its own keys).
  *
  * @param {string[]} strings
@@ -764,7 +764,7 @@ export function createResponder(options = {}) {
   }
 
   /**
-   * Multicast our records (RFC 6762 §8.3), or the TTL=0 goodbye when `goodbye` is set (§10.1).
+   * Multicast our records (RFC 6762 sec.8.3), or the TTL=0 goodbye when `goodbye` is set (sec.10.1).
    *
    * @param {{goodbye?: boolean}} [announceOptions]
    * @returns {Promise<object>}
@@ -903,7 +903,7 @@ export function createResponder(options = {}) {
     const message = decoded.message;
     outcome.handled = true;
 
-    // RFC 6762 §18.3: an opcode other than zero is not a standard query and must be ignored.
+    // RFC 6762 sec.18.3: an opcode other than zero is not a standard query and must be ignored.
     if (message.flags.opcode !== 0) {
       ignoredOpcode += 1;
       outcome.reason = 'opcode';
@@ -924,8 +924,8 @@ export function createResponder(options = {}) {
       return outcome;
     }
 
-    // RFC 6762 §6.7: a query whose source port is not 5353 comes from a one-shot resolver, and MUST be
-    // answered directly, with the query id and question repeated and short TTLs. §5.4: a question with
+    // RFC 6762 sec.6.7: a query whose source port is not 5353 comes from a one-shot resolver, and MUST be
+    // answered directly, with the query id and question repeated and short TTLs. sec.5.4: a question with
     // the unicast-response bit asks for the same treatment.
     const legacy = rinfo.port !== mdnsPort;
     const unicast = legacy || match.unicast_requested;
@@ -1159,7 +1159,7 @@ function waitFor(ms, signal) {
 /**
  * One bounded mDNS scan for W2M service instances.
  *
- * A fresh socket per call, bound to an ephemeral port: RFC 6762 §5.1 requires a one-shot query *not*
+ * A fresh socket per call, bound to an ephemeral port: RFC 6762 sec.5.1 requires a one-shot query *not*
  * to come from port 5353, and a fresh socket also means a scan cannot be poisoned by the previous
  * scan's socket state. The socket is closed on every path, including a throw from a caller's abort
  * signal, and the whole function resolves — it never rejects.
@@ -1177,7 +1177,7 @@ function waitFor(ms, signal) {
  *   the multicast group:5353. A test, or a network where multicast is filtered, can name a unicast
  *   target instead — the query is identically shaped either way.
  * @param {string} [options.bindAddress]
- * @param {boolean} [options.unicastResponse] Set the QU bit (RFC 6762 §5.4).
+ * @param {boolean} [options.unicastResponse] Set the QU bit (RFC 6762 sec.5.4).
  * @param {AbortSignal} [options.signal]
  * @param {() => number} [options.now]
  * @returns {Promise<object>}
@@ -1223,7 +1223,7 @@ export async function discoverServices(options = {}) {
       bound.on('error', (error) => {
         socketError = `${error?.code ?? 'ERROR'}: ${error?.message ?? error}`;
       });
-      // Responses to a one-shot query are unicast back to this socket (§5.1/§6.7), but a responder on
+      // Responses to a one-shot query are unicast back to this socket (sec.5.1/sec.6.7), but a responder on
       // the same link may also multicast its answer, which arrives here too because the socket joined
       // nothing and is simply addressed. Both are handled the same way, and both are hints.
       bound.on('message', (bytes, rinfo) => {