@dotrino/identity 0.115.0 → 0.117.0

package/vault/vendor/proxy-client/client.js

@@ -3,6 +3,7 @@ import { seal, open, isSealed } from './sealing.js'
 import { buildEncPubStatement, readEncPubStatement, isEncPub } from './encpub.js'
 import { WebRTCManager, RTC_TAG, DEFAULT_ICE_SERVERS, loadNodePeerConnection, resolvePeerConnection, pinTurnToIPv4 } from './webrtc.js'
 import { TrafficStats, utf8Length, registerTransport, unregisterTransport } from './stats.js'
+import { splitParts, isPart, Reassembler, DIRECT_PART_CHARS, PROXY_PART_CHARS, QUEUE_MAX_CHARS, RELAY_MAX_CHARS } from './parts.js'
 
 /**
  * Error con un `code` estable.
@@ -67,6 +68,12 @@ export class WebSocketProxyClient {
     this.autoReconnect = options.autoReconnect !== false
     this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5
     this.reconnectDelay = options.reconnectDelay ?? 3000
+    // UN SOCKET QUE NO ABRE NI FALLA. El WebSocket de Node (y el del navegador) no tiene
+    // tope para el saludo: si el TCP entra y nadie contesta el upgrade, se queda en
+    // CONNECTING sin disparar `open`, `error` ni `close`. Como el siguiente reintento solo
+    // se programa desde esos eventos, la cadena de reconexión se paraba ahí, en silencio.
+    // Se abandona el intento pasado este tiempo y cuenta como un fallo más.
+    this.connectTimeout = options.connectTimeout ?? 15000
     this.enableWebRTC = options.enableWebRTC !== false
     this.iceServers = options.iceServers || null
 
@@ -180,7 +187,12 @@ export class WebSocketProxyClient {
     this._handlers = new Map()
     this._pending = new Map() // messageId -> { resolve, reject, timer }
     this._nextId = 1
-    this._tokenWatch = new Map() // messageId -> { token, sobre, peerPubkey, timer }
+    this._tokenWatch = new Map() // messageId -> { token, sobre, peerPubkey, timer, queueFallback }
+    // Mensajes grandes que llegan en partes (parts.js). Uno que se queda a medias se DICE:
+    // con él se pierde el mensaje entero, y eso no puede pasar callado.
+    this._parts = new Reassembler({
+      onExpire: (info) => this._emit('error', { type: 'parts_incomplete', code: 'parts-incomplete', ...info })
+    })
     this._traffic = new TrafficStats()
 
     this._rtc = this.enableWebRTC ? new WebRTCManager({
@@ -225,6 +237,8 @@ export class WebSocketProxyClient {
   connect () {
     return new Promise((resolve, reject) => {
       if (this._connected) return resolve(this.token)
+      // Un reintento que estaba esperando su turno sobra: este `connect()` ya abre uno.
+      if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null }
       this._connectResolve = resolve
       this._connectReject = reject
       this._open()
@@ -493,10 +507,19 @@ export class WebSocketProxyClient {
    */
   async sendSealed (toPubkeys, payload, { peerEncPub, ...opts } = {}) {
     const list = Array.isArray(toPubkeys) ? toPubkeys : [toPubkeys]
+    // Por pubkey el mensaje puede quedarse ESPERANDO en el proxio, y ahí se deja como mucho
+    // 1 MB (parts.js). Lo que pasa de eso no se manda: se dice, y la app decide.
+    const json = JSON.stringify(payload)
+    if (json.length > QUEUE_MAX_CHARS) {
+      throw errorCon(`sendSealed: ${json.length} chars is more than can wait in the proxy (${QUEUE_MAX_CHARS}); send it by token while both ends are connected`, 'too-big-for-queue')
+    }
+    const pieces = json.length > PROXY_PART_CHARS ? splitParts(json, PROXY_PART_CHARS) : [payload]
     // Con la llave puesta a mano se respeta tal cual: quien la pasa está diciendo que ya
     // sabe de quién es (se emparejaron), y un sobre vale para todos los destinatarios.
     if (peerEncPub) {
-      this._sendByPubkeyRaw(list, await this._seal(payload, peerEncPub, list.length === 1 ? list[0] : undefined), opts)
+      for (const piece of pieces) {
+        this._sendByPubkeyRaw(list, await this._seal(piece, peerEncPub, list.length === 1 ? list[0] : undefined), opts)
+      }
       return
     }
     // Sin ella, se averigua. UNA ENVOLTURA POR DESTINATARIO: cada uno tiene su llave, así
@@ -507,7 +530,7 @@ export class WebSocketProxyClient {
     // sin forma de saber cuál mitad.
     const llaves = await Promise.all(list.map(async (pk) => [pk, await this.encPubOf(pk)]))
     for (const [pk, encPub] of llaves) {
-      this._sendByPubkeyRaw([pk], await this._seal(payload, encPub, pk), opts)
+      for (const piece of pieces) this._sendByPubkeyRaw([pk], await this._seal(piece, encPub, pk), opts)
     }
   }
 
@@ -539,10 +562,70 @@ export class WebSocketProxyClient {
       peerEncPub = await this.encPubOf(peerPubkey)
     }
     if (!peerPubkey && tokens.length === 1) peerPubkey = this.pubkeyOfToken(tokens[0]) || undefined
-    const sobre = await this._seal(payload, peerEncPub, peerPubkey)
-    if (tokens.length === 1 && peerPubkey) { this._sendToTokenOrQueue(tokens[0], sobre, peerPubkey); return }
-    // Por `send`, no por `_sendRaw`: así sigue prefiriendo el canal directo si lo hay.
-    this.send(tokens, sobre)
+    // Por token los dos están conectados y NO HAY TOPE (parts.js): lo que no cabe en un
+    // mensaje del camino que toca sale en partes. El tamaño de parte lo decide el camino
+    // de ahora: el canal directo admite mucho menos por mensaje que el proxio.
+    const json = JSON.stringify(payload)
+    const direct = tokens.length === 1 && !!this._rtc?.isOpen(tokens[0])
+    const size = direct ? DIRECT_PART_CHARS : PROXY_PART_CHARS
+    if (json.length <= size) {
+      const sobre = await this._seal(payload, peerEncPub, peerPubkey)
+      if (tokens.length === 1 && peerPubkey) { this._sendToTokenOrQueue(tokens[0], sobre, peerPubkey); return }
+      // Por `send`, no por `_sendRaw`: así sigue prefiriendo el canal directo si lo hay.
+      this.send(tokens, sobre)
+      return
+    }
+    // Por el proxio en vivo hay tope (parts.js): lo que pasa de él solo sale por canal
+    // directo. Se pide el canal para que el siguiente intento lo encuentre abierto.
+    if (!direct && json.length > RELAY_MAX_CHARS) {
+      this._upgradeDirect(tokens)
+      throw errorCon(`sendSealedTo: ${json.length} chars is more than goes through the proxy live (${RELAY_MAX_CHARS}); it needs a direct channel`, 'too-big-for-relay')
+    }
+    // Si el token muere a mitad, lo que quede se iría a la cola por pubkey; solo se permite
+    // si el mensaje entero cabe ahí. Si no, se dice (`too-big-for-queue`), no se deja.
+    const queueFallback = json.length <= QUEUE_MAX_CHARS
+    // Y si el canal directo se cae a mitad, el resto va por el proxio en vivo solo si el
+    // mensaje entero cabe por ahí; si no, se para y se dice (`direct-lost`).
+    const relayFallback = json.length <= RELAY_MAX_CHARS
+    for (const piece of splitParts(json, size)) {
+      const sobre = await this._seal(piece, peerEncPub, peerPubkey)
+      if (tokens.length === 1 && peerPubkey) await this._sendPiece(tokens[0], sobre, peerPubkey, queueFallback, relayFallback)
+      else this.send(tokens, sobre)
+    }
+  }
+
+  /**
+   * POR DÓNDE LE LLEGA AHORA un mensaje a este token: `socket` (la otra punta en esta
+   * máquina), `direct` (WebRTC sin nadie en medio), `turn` (WebRTC por el relevo, que no puede
+   * leer lo que pasa), `proxy` (en vivo por el proxio) u `offline` (no hay conexión: por
+   * pubkey quedaría esperando en el proxio). Cada camino tiene su tope (parts.js), y para eso
+   * existe esto: que la app lo enseñe antes de que el usuario intente algo que no cabe.
+   * `webrtc` es un canal directo abierto del que todavía no se sabe si va por TURN.
+   * @param {string|null} token
+   * @returns {Promise<'socket'|'direct'|'turn'|'webrtc'|'proxy'|'offline'>}
+   */
+  async routeTo (token) {
+    if (!this._connected) return 'offline'
+    if (!token) return 'offline'
+    if (this._rtc?.isOpen(token)) {
+      const peer = this._rtc.peers.get(token)
+      try { return (await this._rtc.probeRoute(peer)) || 'webrtc' } catch (_) { return 'webrtc' }
+    }
+    return 'proxy'
+  }
+
+  /**
+   * Una parte por token: por el canal directo esperando a que vacíe su búfer (sin eso, un
+   * archivo grande lo desborda y el navegador cierra el canal), o por el proxio en vivo con
+   * una pausa corta entre partes, para no chocar con su límite de mensajes por segundo.
+   */
+  async _sendPiece (token, sobre, peerPubkey, queueFallback, relayFallback = true) {
+    if (this._rtc && await this._rtc.sendDirect(token, JSON.stringify(sobre))) return
+    if (!relayFallback) {
+      throw errorCon('the direct channel closed in the middle of a message too big for the proxy', 'direct-lost')
+    }
+    this._sendToTokenOrQueue(token, sobre, peerPubkey, { queueFallback, skipDirect: true })
+    await new Promise((r) => setTimeout(r, 20))
   }
 
   /**
@@ -577,16 +660,16 @@ export class WebSocketProxyClient {
    * `token_gone` para que la app deje de usar ese token. No bloquea a nadie: se manda ya y
    * el arreglo, si hace falta, llega detrás.
    */
-  _sendToTokenOrQueue (token, sobre, peerPubkey) {
+  _sendToTokenOrQueue (token, sobre, peerPubkey, { queueFallback = true, skipDirect = false } = {}) {
     if (this.requireSealed && !this._isSealed(sobre)) {
       throw errorCon('requireSealed: refusing to send a directed message in the clear — use sendSealedTo()', 'unsealed')
     }
     const messageStr = JSON.stringify(sobre)
-    if (this._rtc && this._rtc.trySend(token, messageStr)) return
+    if (!skipDirect && this._rtc && this._rtc.trySend(token, messageStr)) return
     const id = `msg_${this._nextId++}`
     const timer = setTimeout(() => this._tokenWatch.delete(id), 15000)
     timer.unref?.()
-    this._tokenWatch.set(id, { token, sobre, peerPubkey, timer })
+    this._tokenWatch.set(id, { token, sobre, peerPubkey, timer, queueFallback })
     try {
       this._sendRaw({ to: [token], message: messageStr, id })
     } catch (e) {
@@ -605,6 +688,11 @@ export class WebSocketProxyClient {
     this._tokenWatch.delete(data.id)
     if (!Array.isArray(data.failed) || !data.failed.includes(w.token)) return
     this._emit('token_gone', w.token, w.peerPubkey)
+    // Una parte de un mensaje que no cabe en la cola no se deja en el proxio (parts.js).
+    if (!w.queueFallback) {
+      this._emit('error', { type: 'client', error: 'the peer left in the middle of a message too big to wait in the proxy', code: 'too-big-for-queue', peerPubkey: w.peerPubkey })
+      return
+    }
     try { this._sendByPubkeyRaw([w.peerPubkey], w.sobre) } catch (e) { this._emit('error', { type: 'client', error: e.message, code: e.code || null }) }
   }
 
@@ -805,7 +893,16 @@ export class WebSocketProxyClient {
         // Quién selló (la llave de cifrado), si el sobre lo dice: es lo que autentica al
         // remitente, porque solo quien tiene esa privada pudo armarlo.
         const senderEncPub = this.sealing?.senderOf?.(payload) || null
-        this._emit('message', from, opened, { ...meta, sealed: true, ...(senderEncPub ? { senderEncPub } : {}) })
+        const fullMeta = { ...meta, sealed: true, ...(senderEncPub ? { senderEncPub } : {}) }
+        if (isPart(opened)) {
+          // Se agrupa por quien selló: solo esa llave pudo armar cada parte.
+          let whole
+          try { whole = this._parts.add(senderEncPub || meta.fromPubkey || from || '', opened) }
+          catch (e) { this._emit('error', { type: 'bad_part', from, code: e.code || 'bad-part', error: e }); return }
+          if (whole !== null) this._emit('message', from, whole, { ...fullMeta, parts: opened.__dotrino_part.n })
+          return
+        }
+        this._emit('message', from, opened, fullMeta)
       } catch (e) {
         // Sealed to somebody else, or tampered with. Staying quiet is the point.
         this._emit('error', { type: 'undecipherable', from, error: e })
@@ -1242,11 +1339,21 @@ export class WebSocketProxyClient {
 
   _open () {
     registerTransport(this)
+    // El intento anterior, si sigue a medio abrir, se suelta: sus eventos tardíos ya se
+    // ignoran (`ws !== this.ws`), pero el socket quedaría abierto sin dueño.
+    const prev = this.ws
+    if (prev && prev.readyState === 0 /* CONNECTING */) {
+      this.ws = null   // antes de cerrarlo: su `close` ya no es de este cliente
+      try { prev.close() } catch (_) {}
+    }
     const ws = new WebSocket(this.url)
     this.ws = ws
+    const openTimer = this.connectTimeout > 0 ? setTimeout(() => this._onConnectTimeout(ws), this.connectTimeout) : null
+    openTimer?.unref?.()
     // `ws !== this.ws` ⇒ es un socket que ya abandonamos (p.ej. por heartbeat
     // muerto). Ignoramos sus eventos tardíos para no disparar reconexiones dobles.
     ws.addEventListener('open', () => {
+      if (openTimer) clearTimeout(openTimer)
       if (ws !== this.ws) return
       this._connected = true
       this._reconnectAttempts = 0
@@ -1269,6 +1376,7 @@ export class WebSocketProxyClient {
       }
     })
     ws.addEventListener('close', (ev) => {
+      if (openTimer) clearTimeout(openTimer)
       if (ws !== this.ws) return
       this._stopHeartbeat()
       const wasConnected = this._connected
@@ -1301,6 +1409,23 @@ export class WebSocketProxyClient {
     })
   }
 
+  // El intento no abrió ni falló a tiempo: se suelta y se trata como un cierre fallido.
+  _onConnectTimeout (ws) {
+    if (ws !== this.ws || this._connected) return
+    this.ws = null   // a partir de acá, los eventos tardíos de `ws` se ignoran
+    try { ws.close() } catch (_) {}
+    const err = errorCon(`could not open the connection to ${this.url} in ${Math.round(this.connectTimeout / 1000)}s`, 'CONNECT_TIMEOUT')
+    this._emit('error', { type: 'connect_timeout', error: err })
+    if (this._connectReject) {
+      this._connectReject(err)
+      this._connectResolve = null
+      this._connectReject = null
+    }
+    // Lo mismo que en `close`: se sigue reintentando solo si esto ya era un reintento. Un
+    // `connect()` inicial que no abre se rechaza y ya.
+    if (this._reconnectAttempts > 0 && this.autoReconnect) this._scheduleReconnect()
+  }
+
   // ---------- heartbeat ----------
 
   _startHeartbeat () {

package/vault/vendor/proxy-client/index.js

@@ -11,6 +11,7 @@ export {
 } from './encpub.js'
 
 export { listTransports, routeOf } from './stats.js'
+export { PART_TAG, DIRECT_PART_CHARS, PROXY_PART_CHARS, QUEUE_MAX_CHARS, RELAY_MAX_CHARS } from './parts.js'
 export { logStats, formatStats, netReport, splitPeers } from './stats-log.js'
 
 import { WebSocketProxyClient } from './client.js'

package/vault/vendor/proxy-client/parts.js

@@ -0,0 +1,127 @@
+/**
+ * MENSAJES GRANDES, EN PARTES (0.33.0).
+ *
+ * Un mensaje dirigido tiene techo en cada camino: el canal directo (WebRTC) rechaza lo que
+ * pasa de 64 KiB hacia libwebrtc y la trama del proxio es de 1 MB. Antes, lo que no cabía
+ * en el canal directo se iba callado por el proxio (y llegaba desordenado), y lo que no
+ * cabía en la trama no salía. Ahora el pilar parte el mensaje y la otra punta lo rearma:
+ * la app manda y recibe un objeto entero, como siempre.
+ *
+ * La regla del dueño (2026-10-15), que es lo que decide los topes:
+ *   - por el canal directo (WebRTC, también por TURN) NO HAY TOPE;
+ *   - por el proxio EN VIVO (los dos conectados, sin canal directo), como mucho 25 MB de
+ *     archivo: cada parte cruza el VPS dos veces, y uno de 25 MB ya son ~90 MB de tráfico.
+ *     Más que eso lanza `too-big-for-relay`, y sale cuando haya canal directo;
+ *   - lo que se queda ESPERANDO en el proxio (por pubkey, el otro desconectado) es como
+ *     mucho 8 MB de archivo: una foto de teléfono pesa 2-5 MB, y con 1 MB (lo primero que se
+ *     pensó) casi ninguna habría podido esperar. Lo que pasa de ahí no se deja en el proxio:
+ *     se lanza `too-big-for-queue`.
+ *
+ * Cada parte va SELLADA por su cuenta (el pilar sella cada una como cualquier mensaje), así
+ * que el proxio no ve ni el contenido ni cuántas partes son de qué. El rearmado agrupa por la
+ * llave que selló: nadie más puede colar una parte en el mensaje de otro.
+ */
+
+export const PART_TAG = '__dotrino_part'
+
+/** Parte por el canal directo: por debajo de los 64 KiB que acepta libwebrtc, ya sellada. */
+export const DIRECT_PART_CHARS = 40 * 1024
+/** Parte por el proxio: sellada (×1,37) cabe holgada en la trama de 1 MB. */
+export const PROXY_PART_CHARS = 512 * 1024
+/**
+ * Lo más que se deja esperando en el proxio. Se mide sobre el JSON del mensaje: 8 MB de
+ * archivo en base64 ocupan ~10,7 MB, y se deja margen para lo que va alrededor.
+ */
+export const QUEUE_MAX_CHARS = 11 * 1024 * 1024
+/** Lo más que pasa por el proxio EN VIVO: 25 MB de archivo son ~33,4 MB en base64. */
+export const RELAY_MAX_CHARS = 34 * 1024 * 1024
+
+/** Rearmado: lo que se acepta guardar a medias, y cuánto se espera a la parte siguiente. */
+const RECV_MAX_CHARS = 512 * 1024 * 1024
+const RECV_IDLE_MS = 5 * 60 * 1000
+const MAX_PARTS = 1 << 20
+
+/** El id de un mensaje en partes: al azar, para que dos mensajes no se mezclen. */
+export function partId () {
+  const b = new Uint8Array(12)
+  globalThis.crypto.getRandomValues(b)
+  return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('')
+}
+
+/** Las partes (ya como objetos para sellar) de un JSON de `json.length` > `size`. */
+export function splitParts (json, size) {
+  const n = Math.ceil(json.length / size)
+  const id = partId()
+  const out = []
+  for (let i = 0; i < n; i++) out.push({ [PART_TAG]: { id, i, n }, d: json.slice(i * size, (i + 1) * size) })
+  return out
+}
+
+export const isPart = (o) => !!(o && typeof o === 'object' && o[PART_TAG])
+
+/**
+ * Rearma los mensajes. `add` devuelve el mensaje entero cuando llega la última parte, `null`
+ * mientras falten, y lanza con `code` si la parte no vale (se dice: una parte mala no puede
+ * desaparecer en silencio, porque el mensaje entero se pierde con ella).
+ */
+export class Reassembler {
+  constructor ({ onExpire = () => {} } = {}) {
+    this._open = new Map()
+    this._chars = 0
+    this._onExpire = onExpire
+  }
+
+  /** @param {string} sender quién selló (agrupa) @param {any} part */
+  add (sender, part) {
+    const p = part[PART_TAG]
+    const d = part.d
+    if (!p || typeof p.id !== 'string' || p.id.length > 64 ||
+        !Number.isInteger(p.n) || !Number.isInteger(p.i) || p.n < 2 || p.n > MAX_PARTS ||
+        p.i < 0 || p.i >= p.n || typeof d !== 'string') {
+      throw Object.assign(new Error('malformed message part'), { code: 'bad-part' })
+    }
+    const key = `${sender}|${p.id}`
+    let a = this._open.get(key)
+    if (!a) {
+      a = { n: p.n, got: new Array(p.n), count: 0, chars: 0, timer: null }
+      this._open.set(key, a)
+    }
+    if (a.n !== p.n) {
+      this._drop(key)
+      throw Object.assign(new Error('message parts disagree on their count'), { code: 'bad-part' })
+    }
+    if (a.got[p.i] === undefined) {
+      if (this._chars + d.length > RECV_MAX_CHARS) {
+        this._drop(key)
+        throw Object.assign(new Error('too much of a message in parts is pending'), { code: 'parts-too-big' })
+      }
+      a.got[p.i] = d
+      a.count++
+      a.chars += d.length
+      this._chars += d.length
+    }
+    if (a.timer) clearTimeout(a.timer)
+    if (a.count === a.n) {
+      this._drop(key)
+      try { return JSON.parse(a.got.join('')) }
+      catch (_) { throw Object.assign(new Error('a message in parts did not join into JSON'), { code: 'bad-part' }) }
+    }
+    a.timer = setTimeout(() => {
+      const missing = a.n - a.count
+      this._drop(key)
+      this._onExpire({ id: p.id, parts: a.n, missing })
+    }, RECV_IDLE_MS)
+    a.timer.unref?.()
+    return null
+  }
+
+  _drop (key) {
+    const a = this._open.get(key)
+    if (!a) return
+    if (a.timer) clearTimeout(a.timer)
+    this._chars -= a.chars
+    this._open.delete(key)
+  }
+
+  clear () { for (const k of [...this._open.keys()]) this._drop(k) }
+}

package/vault/vendor/proxy-client/webrtc.js

@@ -192,6 +192,29 @@ export class WebRTCManager {
     return false
   }
 
+  /**
+   * Mandar por el canal directo ESPERANDO a que su búfer baje. Para las partes de un
+   * mensaje grande: soltarlas todas de golpe desborda el búfer del canal, el navegador lo
+   * cierra y el resto se pierde. Devuelve false si el canal no está (o se cerró), y quien
+   * llama sigue por el proxio.
+   */
+  async sendDirect (to, payloadString, highWater = 1024 * 1024) {
+    const peer = this.peers.get(to)
+    const dc = peer && peer.dc
+    if (!dc || dc.readyState !== 'open') return false
+    while (dc.bufferedAmount > highWater) {
+      await new Promise((r) => setTimeout(r, 15))
+      if (dc.readyState !== 'open') return false
+    }
+    try {
+      dc.send(payloadString)
+      this.count?.('out', to, utf8Length(payloadString), peer.route || 'webrtc')
+      return true
+    } catch (_) {
+      return false
+    }
+  }
+
   /** Optional: explicitly preconnect to a peer. */
   connect (to) {
     const peer = this._ensurePeer(to)

package/vault/vendor/roadmap/VERSION.txt

@@ -0,0 +1,3 @@
+Copia vendorizada de @dotrino/roadmap@0.4.17 (dotrino-roadmap/src/{index,manifests}.js).
+NO se edita a mano: la escribe `node vendor.mjs` y la vigila test/vendor-up-to-date.test.mjs.
+El registro de versiones rotas que viaja con cada versión. Importa @dotrino/compat/ranges.

package/vault/vendor/roadmap/index.js

@@ -0,0 +1,108 @@
+/**
+ * @dotrino/roadmap — EL REGISTRO COMÚN, COMO PIEZA DE CONSULTA.
+ *
+ * Los manifiestos de este repo dicen **qué versión va cada producto, qué protocolo habla,
+ * qué rangos necesita de los demás y qué versiones se saben rotas**. Esta librería es la
+ * forma de leerlos: cada producto la importa en vez de abrir el JSON a mano, porque
+ * treinta piezas parseando el mismo archivo a su manera son treinta formas de equivocarse
+ * y ninguna hace ruido cuando se equivoca.
+ *
+ * REPARTO DE TRABAJO, para que no se mezcle:
+ *
+ *   · **`@dotrino/compat`** decide. Es la lógica: declarar, comparar, avisar.
+ *   · **esto** es el registro. Son los datos, y se editan aquí.
+ *
+ * Va como `peerDependency` de `@dotrino/compat` a propósito: un pilar dentro de otro se
+ * cuela anidado a cada consumidor, y ya pasó (`PENDIENTES.md`, «pilar anidado»).
+ *
+ * EL MANIFIESTO ES POLÍTICA DEL CÓDIGO (dueño, 2026-09-04): viaja con la versión que lo
+ * trae. Lo que llega por la red es el **aviso** firmado de `@dotrino/compat/advisory`, que
+ * suma incompatibilidades y no quita ninguna.
+ */
+import { satisfies } from '@dotrino/compat/ranges'
+import { MANIFESTS } from './manifests.js'
+
+/**
+ * NADA DE DISCO, y esto costó un binario que no arrancaba.
+ *
+ * La primera versión leía los JSON con `fileURLToPath(import.meta.url)` calculado AL
+ * IMPORTARSE. En un ejecutable único eso no existe: la bóveda murió al arrancar con «The
+ * "path" argument must be of type string», y en un navegador no habría arrancado nunca.
+ *
+ * Los consumen ~30 PWAs, varios daemons y un binario. Un registro que hay que leer del
+ * disco no sirve para eso, así que los manifiestos van DENTRO del código
+ * (`src/manifests.js`, generado desde `manifests/*.json`).
+ */
+
+/** Los manifiestos que trae esta versión. Hay uno («dotrino») y caben varios. */
+export function manifestNames () {
+  return Object.keys(MANIFESTS).sort()
+}
+
+/**
+ * Un manifiesto por nombre. LANZA si no está: quien pregunta por un registro que no existe
+ * tiene un error, y devolverle un objeto vacío lo convertiría en «todo compatible».
+ */
+export function loadManifest (name = 'dotrino') {
+  const m = Object.hasOwn(MANIFESTS, String(name)) ? MANIFESTS[String(name)] : null
+  if (!m) throw new Error(`roadmap: there is no manifest called "${name}"`)
+  return m
+}
+
+/** Los productos que el registro conoce. */
+export const products = (m) => Object.keys(m?.products || {}).sort()
+
+/** La ficha de un producto, o `null` si el registro no lo conoce. */
+export const productOf = (m, product) => m?.products?.[product] || null
+
+/** La versión que el registro da por vigente. `null` si no lo conoce. */
+export const currentOf = (m, product) => productOf(m, product)?.current || null
+
+/** El rango que `product` necesita de `peer`, o `null` si no exige nada. */
+export function requirementFor (m, product, peer) {
+  const p = productOf(m, product)
+  if (!p) return null
+  return p.requires?.[peer] ?? null
+}
+
+/**
+ * ¿La versión de `peer` cumple lo que `product` necesita?
+ *
+ * Tres respuestas y ninguna es «bueno, adelante»:
+ *   · `true`  — cumple.
+ *   · `false` — no cumple, y `reason` dice qué se esperaba.
+ *   · cuando el registro NO exige nada, cumple: no exigir es una decisión, no una laguna.
+ *
+ * Si el registro no conoce al producto que pregunta, es `false`: preguntar por quien no
+ * está en el registro no puede salir que sí.
+ */
+export function meets (m, { product, peer, version }) {
+  if (!productOf(m, product)) {
+    return { ok: false, reason: `the registry does not know "${product}"` }
+  }
+  const rango = requirementFor(m, product, peer)
+  if (rango == null) return { ok: true, reason: '' }
+  if (satisfies(version, rango)) return { ok: true, reason: '' }
+  return { ok: false, reason: `${product} needs ${peer} ${rango} and this one is ${version}` }
+}
+
+/** La lista de rotas del registro, lista para pasarla a `check` de `@dotrino/compat`. */
+export const brokenOf = (m) => Array.isArray(m?.broken) ? m.broken : []
+
+/** Lo que el administrador enseña: qué versión debería ir cada pieza, según el registro. */
+export function summary (m) {
+  return {
+    manifest: m?.manifest || null,
+    seq: m?.seq ?? null,
+    issued: m?.issued || null,
+    products: products(m).map((p) => ({
+      product: p,
+      current: currentOf(m, p),
+      protocol: productOf(m, p)?.protocol ?? null,
+      requires: productOf(m, p)?.requires || {}
+    })),
+    broken: brokenOf(m)
+  }
+}
+
+export default { manifestNames, loadManifest, products, productOf, currentOf, requirementFor, meets, brokenOf, summary }