@ajuarezso/lienzo-mcp 0.0.0-stage → 0.3.0

package/lib/escucha.mjs

@@ -0,0 +1,269 @@
+// «Timbre» de lienzo_esperar: escucha la sala en tiempo real y solo avisa que ALGO cambió.
+//
+// Por qué: esperar mirando la sala por REST cuesta lecturas aunque no pase nada (cada runQuery cobra
+// al menos 1 lectura, más las de las reglas). Con un listener de Firestore, una sala quieta no cuesta
+// nada: se paga una lectura por documento que cambia. El timbre NO entrega datos: cuando suena,
+// lienzo_esperar hace UNA pasada de novedades() por REST, igual que antes (mismo contrato, mismo sobre
+// de seguridad, mismas marcas). Medido en docs/costo-esperar.md.
+//
+// Qué escucha (tres consultas chicas, nunca la colección entera: el estado inicial se cobra):
+//   1. la tarjeta más nueva          orderBy(creadaEn desc) limit 1          → llegó una tarjeta
+//   2. la última edición             editadaEn > al abrir, desc, limit 1     → alguien editó
+//   3. mis tareas                    autorId == yo, tipo == 'tarea'          → cambió estado/respuesta/tomadaPor
+// Lo propio (tarjetas o ediciones mías) y lo que solo mueve el lienzo (posicion, marcoId) no suena.
+//
+// Usa el SDK web de Firestore en Node (gRPC) con el idToken de la sesión del puente: se le entrega por
+// el componente interno «auth-internal», el mismo por el que lo recibe de Firebase Auth en la web. Las
+// reglas se aplican igual: el listener es el mismo participante que el REST, sin privilegios.
+// Si algo de esto falla (paquete, red, reglas), el timbre queda «no sano» y lienzo_esperar vuelve a
+// mirar por REST con la espera creciente de siempre.
+
+export const ABRIR_TIMEOUT_MS = 15 * 1000;
+/** LIENZO_DEPURAR=1: el timbre cuenta por stderr cada vez que suena y por qué (para medir, no para el día a día). */
+const DEPURAR = process.env.LIENZO_DEPURAR === '1';
+/** Campos cuyo cambio en una tarea mía es novedad (los mismos que mira _cambiosEnMisTareas). */
+const CAMPOS_TAREA = ['estado', 'respuesta', 'tomadaPor'];
+
+let siguiente = 0;
+
+/** Carga perezosa del SDK: el puente arranca igual de rápido y, si el paquete falta, se sigue por REST. */
+async function cargarSdk() {
+  const [app, componente, firestore] = await Promise.all([
+    import('@firebase/app'), import('@firebase/component'), import('@firebase/firestore'),
+  ]);
+  // stdout es del protocolo MCP: el SDK solo puede hablar por stderr (warn/error van ahí)
+  firestore.setLogLevel('error');
+  return { app, componente, firestore };
+}
+
+/** «2026-10-20T15:00:00.123456Z» → Timestamp exacto (Date perdería los microsegundos). */
+function aTimestamp(firestore, iso) {
+  const m = /^(.*T\d\d:\d\d:\d\d)(?:\.(\d+))?Z$/.exec(iso || '');
+  if (!m) return firestore.Timestamp.fromDate(new Date(iso));
+  const segundos = Math.floor(Date.parse(`${m[1]}Z`) / 1000);
+  const nanos = Number((m[2] || '').padEnd(9, '0').slice(0, 9));
+  return new firestore.Timestamp(segundos, nanos);
+}
+
+export class Timbre {
+  /**
+   * @param {{ config: object, sesion: { uid: string, token: Function, renovar: Function, idToken?: string },
+   *           salaId: string, miId: string, desde?: string|null, sdk?: object, log?: Function }} o
+   *   miId: el id de participante de este puente (autorId de lo que publica). desde: marca de edición al abrir.
+   */
+  constructor(o) {
+    this.config = o.config;
+    this.sesion = o.sesion;
+    this.salaId = o.salaId;
+    this.miId = o.miId;
+    this.desde = o.desde ?? null;
+    this._sdk = o.sdk ?? null;
+    this.log = o.log ?? ((m) => console.error(`[lienzo] ${m}`));
+    /** Sube con cada cambio que importa. lienzo_esperar consulta cuando no es el que vio la última vez. */
+    this.version = 0;
+    /** Cuántos cambios de documento llegaron por el listener (cada uno se cobra como 1 lectura). */
+    this.cambiosRecibidos = 0;
+    this.error = null;
+    this._estados = new Map(); // nombre de la consulta → { servidor: bool }
+    this._tareas = new Map(); // id → 'estado|respuesta|tomadaPor' visto
+    this._ultimaEdicion = null; // 'id@editadaEn' de la última edición vista
+    this._bajas = [];
+    this._esperando = new Set();
+    this._cerrado = false;
+    this._db = null;
+    this._app = null;
+  }
+
+  /** Sano = las tres consultas tienen respuesta del servidor y ninguna falló. Si no, se mira por REST. */
+  get sano() {
+    return !this._cerrado && !this.error && this._estados.size === 3 && [...this._estados.values()].every((e) => e.servidor);
+  }
+
+  _sonar(motivo) {
+    this.version++;
+    if (DEPURAR) this.log(`${new Date().toISOString().slice(11, 19)} timbre: sonó (${motivo}) → versión ${this.version}`);
+    for (const r of this._esperando) r(motivo);
+  }
+
+  /** Abre los tres listeners y espera su primera respuesta del servidor. Lanza si no lo logra. */
+  async abrir() {
+    const sdk = this._sdk ?? await cargarSdk();
+    const { initializeApp, _addOrOverwriteComponent } = sdk.app;
+    const { Component } = sdk.componente;
+    const fs = sdk.firestore;
+    const sesion = this.sesion;
+
+    this._app = initializeApp({ projectId: this.config.projectId, apiKey: this.config.apiKey }, `lienzo-timbre-${++siguiente}`);
+    _addOrOverwriteComponent(this._app, new Component('auth-internal', () => ({
+      getUid: () => sesion.uid ?? null,
+      getToken: async (forzar) => ({ accessToken: forzar ? await sesion.renovar() : await sesion.token() }),
+      // Firestore espera un primer aviso con el token actual antes de abrir el stream.
+      addAuthTokenListener: (l) => { Promise.resolve().then(() => l(sesion.idToken ?? null)); },
+      removeAuthTokenListener: () => {},
+    }), 'PRIVATE'));
+    this._db = fs.getFirestore(this._app);
+    if (this.config.emuladorFirestore) {
+      const [host, puerto] = this.config.emuladorFirestore.split(':');
+      fs.connectFirestoreEmulator(this._db, host, Number(puerto));
+    }
+
+    const tarjetas = fs.collection(this._db, 'salas', this.salaId, 'tarjetas');
+    const consultas = {
+      nuevas: fs.query(tarjetas, fs.orderBy('creadaEn', 'desc'), fs.limit(1)),
+      ediciones: fs.query(tarjetas, fs.where('editadaEn', '>', aTimestamp(fs, this.desde ?? new Date().toISOString())),
+        fs.orderBy('editadaEn', 'desc'), fs.limit(1)),
+      tareas: fs.query(tarjetas, fs.where('autorId', '==', this.miId), fs.where('tipo', '==', 'tarea')),
+    };
+
+    const listo = new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error(`el listener no respondió en ${ABRIR_TIMEOUT_MS / 1000} s`)), ABRIR_TIMEOUT_MS);
+      this._alListo = () => { if (this.sano) { clearTimeout(t); resolve(); } };
+      this._alFallar = (e) => { clearTimeout(t); reject(e); };
+    });
+
+    for (const [nombre, q] of Object.entries(consultas)) {
+      this._estados.set(nombre, { servidor: false, primera: true });
+      this._bajas.push(fs.onSnapshot(q, { includeMetadataChanges: true },
+        (snap) => this._alSnapshot(nombre, snap),
+        (e) => this._alError(nombre, e)));
+    }
+    try {
+      await listo;
+    } catch (e) {
+      await this.cerrar();
+      throw e;
+    }
+    return this;
+  }
+
+  _alSnapshot(nombre, snap) {
+    const estado = this._estados.get(nombre);
+    const estabaSano = this.sano;
+    if (DEPURAR) this.log(`${new Date().toISOString().slice(11, 19)} timbre: snapshot ${nombre} fromCache=${snap.metadata.fromCache} cambios=${snap.docChanges().map((c) => `${c.type}:${c.doc.id}`).join(',') || '-'}`);
+    estado.servidor = !snap.metadata.fromCache;
+    // «primera» = el estado inicial que manda el servidor (lo que ya había): no es novedad
+    const primera = estado.primera;
+    if (!snap.metadata.fromCache) estado.primera = false;
+    let importa = false;
+    for (const c of snap.docChanges()) {
+      if (!snap.metadata.fromCache) this.cambiosRecibidos++;
+      const d = c.doc.data();
+      if (nombre === 'tareas') {
+        const huella = CAMPOS_TAREA.map((k) => JSON.stringify(d[k] ?? null)).join('|');
+        const antes = this._tareas.get(c.doc.id);
+        if (c.type === 'removed') { this._tareas.delete(c.doc.id); continue; }
+        this._tareas.set(c.doc.id, huella);
+        // una tarea mía nueva la publiqué yo; un movimiento en el lienzo no cambia la huella
+        if (!primera && c.type === 'modified' && antes !== huella) importa = true;
+      } else if (nombre === 'ediciones') {
+        // la misma tarjeta editada dos veces sigue arriba: llega como «modified», no como «added»
+        const clave = `${d.editadaEn?.seconds}.${d.editadaEn?.nanoseconds}`;
+        const antes = this._ultimaEdicion;
+        if (c.type === 'removed') continue;
+        this._ultimaEdicion = `${c.doc.id}@${clave}`;
+        if (!primera && antes !== this._ultimaEdicion && d.autorId !== this.miId) importa = true;
+      } else if (!primera && c.type === 'added' && d.autorId !== this.miId) {
+        // la tarjeta más nueva cambió y no es mía; lo mío ya lo sé
+        importa = true;
+      }
+    }
+    if (importa) this._sonar(nombre);
+    else if (!estabaSano && this.sano) this._sonar('volvió la conexión'); // pudo perderse algo en el corte
+    else if (estabaSano && !this.sano) this._sonar('sin conexión'); // despierta a quien espera: pasa a REST
+    this._alListo?.();
+  }
+
+  _alError(nombre, e) {
+    this.error = e;
+    this.log(`el listener «${nombre}» falló (${e.code || e.message}); lienzo_esperar sigue mirando por REST`);
+    this._alFallar?.(e);
+    this._sonar('error');
+  }
+
+  /**
+   * Espera un cambio hasta `ms`. Resuelve true si sonó (o el timbre dejó de estar sano: quien espera
+   * tiene que volver a mirar), false si se acabó el tiempo. Una señal abortada resuelve false.
+   */
+  esperarCambio(ms, signal) {
+    return new Promise((resolve) => {
+      if (signal?.aborted) return resolve(false);
+      let fin = null;
+      const listo = (v) => {
+        clearTimeout(t);
+        this._esperando.delete(fin);
+        signal?.removeEventListener('abort', alAbortar);
+        resolve(v);
+      };
+      fin = () => listo(true);
+      const alAbortar = () => listo(false);
+      const t = setTimeout(() => listo(false), Math.max(0, ms));
+      this._esperando.add(fin);
+      signal?.addEventListener('abort', alAbortar, { once: true });
+    });
+  }
+
+  async cerrar() {
+    if (this._cerrado) return;
+    this._cerrado = true;
+    for (const baja of this._bajas.splice(0)) { try { baja(); } catch { /* ya cerrado */ } }
+    for (const r of this._esperando) r('cerrado');
+    const sdk = this._sdk;
+    try {
+      if (this._db) await (sdk?.firestore ?? await import('@firebase/firestore')).terminate(this._db);
+      if (this._app) await (sdk?.app ?? await import('@firebase/app')).deleteApp(this._app);
+    } catch (e) {
+      this.log(`no pude cerrar el listener: ${e.message}`);
+    }
+  }
+}
+
+// ── un timbre por puente, atado a la sala y a la identidad ───────────────────
+export const REINTENTO_MS = 5 * 60 * 1000;
+const timbres = new WeakMap(); // lienzo → { clave, timbre, abriendo, falloEn }
+
+/**
+ * El timbre de la sala en la que está `lienzo`, abierto la primera vez que se espera y reusado entre
+ * llamadas (abrirlo cobra su estado inicial; tenerlo abierto en una sala quieta, nada). Si se cambia de
+ * sala o de identidad se cierra y se abre otro. Si no se puede abrir devuelve null (lienzo_esperar mira
+ * por REST) y no se reintenta hasta dentro de 5 min.
+ * @param {{ salaId: string|null, yo: { id: string }|null, sesion: object, config: object, marca?: string|null, marcaEdicion?: string|null }} lienzo
+ */
+export async function timbreDe(lienzo, { crear = (o) => new Timbre(o).abrir(), ahora = Date.now } = {}) {
+  if (process.env.LIENZO_SIN_TIMBRE === '1' || !lienzo.salaId || !lienzo.yo?.id) return null;
+  const clave = `${lienzo.salaId}|${lienzo.yo.id}|${lienzo.sesion.uid}`;
+  let e = timbres.get(lienzo);
+  if (e && e.clave !== clave) {
+    await e.abriendo; // uno que se está abriendo no se pierde: se espera a que exista para cerrarlo
+    await e.timbre?.cerrar();
+    e = null;
+  }
+  if (!e) {
+    e = { clave, timbre: null, abriendo: null, falloEn: null };
+    timbres.set(lienzo, e);
+  }
+  if (e.timbre && (e.timbre.error || e.timbre._cerrado)) {
+    // un listener que falló (p. ej. reglas) no se recupera solo: se cierra y se reintenta más tarde
+    await e.timbre.cerrar();
+    e.timbre = null;
+    e.falloEn = ahora();
+  }
+  if (e.timbre) return e.timbre;
+  if (e.falloEn != null && ahora() - e.falloEn < REINTENTO_MS) return null;
+  e.abriendo ??= crear({
+    config: lienzo.config, sesion: lienzo.sesion, salaId: lienzo.salaId, miId: lienzo.yo.id,
+    desde: lienzo.marcaEdicion ?? lienzo.marca ?? null,
+  }).then((t) => { e.timbre = t; e.falloEn = null; return t; }, (err) => {
+    console.error(`[lienzo] no pude escuchar la sala en tiempo real (${err.code || err.message}); lienzo_esperar mira por REST`);
+    e.falloEn = ahora();
+    return null;
+  }).finally(() => { e.abriendo = null; });
+  return e.abriendo;
+}
+
+/** Cierra el timbre de `lienzo` (al apagar el puente: el stream de gRPC no deja terminar al proceso). */
+export async function cerrarTimbre(lienzo) {
+  const e = timbres.get(lienzo);
+  timbres.delete(lienzo);
+  await e?.abriendo; // si se estaba abriendo, se espera a que exista (no queda huérfano)
+  await e?.timbre?.cerrar();
+}

package/lib/esperar.mjs

@@ -0,0 +1,131 @@
+// Espera acotada de lienzo_esperar. Nunca es un bucle infinito: el tope duro es MAX_SEGUNDOS, pida lo
+// que pida el agente.
+//
+// Dos modos (costo medido en docs/costo-esperar.md):
+//   · con timbre (listener en tiempo real, lib/escucha.mjs): no consulta nada mientras la sala está
+//     quieta; cuando el timbre suena hace UNA pasada de `consultar`. Sala quieta = 0 lecturas.
+//   · sin timbre (o si el timbre se cae): long-poll con espera creciente, consulta, y si no hay nada espera
+//     2,5 s, luego 3,75 s, 5,6 s… hasta 15 s entre consultas. Cada consulta cuesta lecturas aunque no
+//     traiga nada, y el plan gratis (Spark) da 50 000 por día para todo el proyecto.
+
+export const MAX_SEGUNDOS = 60;
+export const INTERVALO_MS = 2500;
+export const INTERVALO_MAX_MS = 15000;
+export const FACTOR = 1.5;
+/** Cuando suena el timbre se espera un poco antes de mirar: una ráfaga (una lista de 9) se lee de una vez. */
+export const AGRUPAR_MS = 300;
+/** Si el timbre se cae, cuánto se espera a que vuelva solo antes de pasar a mirar por REST. */
+export const GRACIA_MS = 10 * 1000;
+
+const dormirReal = (ms, signal) =>
+  new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+
+/**
+ * @param {(signal?: AbortSignal) => Promise<any>} consultar  devuelve algo "verdadero" cuando hay novedades
+ * @param {{ segundos?: number, intervaloMs?: number, maxIntervaloMs?: number, factor?: number,
+ *           signal?: AbortSignal, ahora?: () => number, dormir?: Function,
+ *           timbre?: { sano: boolean, version: number, visto?: number|null, esperarCambio: Function } | null }} o
+ *   intervaloMs es la primera espera del long-poll (por defecto 2,5 s); cada espera vacía la multiplica por
+ *   `factor` hasta `maxIntervaloMs`. Quien llama puede guardar `intervalo` y pasarlo en la siguiente espera
+ *   para no volver a empezar desde 2,5 s si la sala sigue quieta.
+ *   timbre: si está sano, se espera a que suene en vez de consultar. `timbre.visto` es la versión que ya se
+ *   miró: si no cambió desde la última consulta vacía, la espera arranca sin consultar.
+ * @returns {Promise<{ resultado: any, consultas: number, agotado: boolean, cancelado: boolean, intervalo: number, modo: 'timbre'|'rest', version?: number }>}
+ */
+export async function esperarNovedades(consultar, o = {}) {
+  const segundos = Math.min(Math.max(Number(o.segundos) || 30, 1), MAX_SEGUNDOS);
+  const ahora = o.ahora || Date.now;
+  const limite = ahora() + segundos * 1000;
+  // un timbre que no está sano igual se usa: abajo se le da un margen para volver antes de mirar por REST
+  const timbre = o.timbre ?? null;
+  if (!timbre) return sondear(consultar, o, limite, 0);
+
+  const dormir = o.dormir || dormirReal;
+  let consultas = 0;
+  const fin = (extra) => ({ resultado: null, consultas, agotado: false, cancelado: false, intervalo: o.intervaloMs ?? INTERVALO_MS, modo: 'timbre', ...extra });
+  for (;;) {
+    if (o.signal?.aborted) return fin({ cancelado: true });
+    if (!timbre.sano) {
+      // Un corte corto (el token se renueva a la hora, el servidor recicla el stream) se arregla solo en 1–2 s:
+      // se le da un margen antes de mirar por REST. Medido: sin margen, cada corte costaba ~25 lecturas.
+      // Si el servidor negó el permiso (te quitaron, saliste, se borró) no hay nada que esperar: se mira por REST ya
+      // y el error explica por qué.
+      // (o si otra herramienta lo cerró porque ya no estás en la sala)
+      const denegado = timbre.error?.code === 'permission-denied' || timbre._cerrado === true;
+      const gracia = Math.min(limite, ahora() + (denegado ? 0 : GRACIA_MS));
+      while (!timbre.sano && ahora() < gracia && !o.signal?.aborted) await timbre.esperarCambio(gracia - ahora(), o.signal);
+      if (o.signal?.aborted) return fin({ cancelado: true });
+      if (timbre.sano) continue; // volvió: el timbre ya sonó («volvió la conexión») y se pone al día con una pasada
+      // sigue caído: el resto del tiempo se mira por REST, desde 2,5 s
+      timbre.visto = null;
+      if (ahora() >= limite) return fin({ agotado: true });
+      return sondear(consultar, { ...o, intervaloMs: INTERVALO_MS }, limite, consultas);
+    }
+    if (timbre.version !== timbre.visto) {
+      if (timbre.visto != null) await dormir(Math.min(AGRUPAR_MS, Math.max(0, limite - ahora())), o.signal);
+      if (o.signal?.aborted) return fin({ cancelado: true });
+      const version = timbre.version; // lo que llegue mientras se consulta vuelve a sonar
+      consultas++;
+      let resultado;
+      try {
+        resultado = await consultar(o.signal);
+      } catch (e) {
+        if (o.signal?.aborted) return fin({ cancelado: true });
+        throw e;
+      }
+      if (resultado) {
+        // Lo entregado puede salir recortado (tope de 60 000 caracteres): por si acaso la próxima espera mira
+        // otra vez. Quien formatea la respuesta y ve que entró entera pone timbre.visto = version (entregado()).
+        timbre.visto = null;
+        return fin({ resultado, version });
+      }
+      timbre.visto = version;
+      continue; // si sonó durante la consulta, se mira de nuevo
+    }
+    const resta = limite - ahora();
+    if (resta <= 0) return fin({ agotado: true });
+    await timbre.esperarCambio(resta, o.signal);
+  }
+}
+
+/** Long-poll con espera creciente (el modo de siempre, y el respaldo cuando no hay timbre). */
+async function sondear(consultar, o, limite, consultasPrevias) {
+  const maximo = Math.max(o.maxIntervaloMs ?? INTERVALO_MAX_MS, 10);
+  const factor = Math.max(o.factor ?? FACTOR, 1);
+  let intervalo = Math.min(Math.max(o.intervaloMs ?? INTERVALO_MS, 10), maximo);
+  const ahora = o.ahora || Date.now;
+  const dormir = o.dormir || dormirReal;
+  let consultas = consultasPrevias;
+  const fin = (extra) => ({ resultado: null, consultas, agotado: false, cancelado: false, intervalo, modo: 'rest', ...extra });
+
+  for (;;) {
+    if (o.signal?.aborted) return fin({ cancelado: true });
+    consultas++;
+    let resultado;
+    try {
+      resultado = await consultar(o.signal);
+    } catch (e) {
+      if (o.signal?.aborted) return fin({ cancelado: true }); // se cortó el fetch en curso
+      throw e;
+    }
+    if (resultado) return fin({ resultado });
+    const resta = limite - ahora();
+    if (resta <= 0) return fin({ agotado: true });
+    await dormir(Math.min(intervalo, resta), o.signal);
+    intervalo = Math.min(intervalo * factor, maximo);
+  }
+}
+
+/** Respuesta de lienzo_leer / lienzo_esperar que no entregó todo (lo dice formatearLote). */
+export const RE_RECORTADA = /Respuesta recortada|Había más de/;
+
+/**
+ * Tras formatear lo que trajo una espera con timbre: si la respuesta entró entera, lo consultado ya está
+ * entregado y la próxima espera no necesita volver a mirar (ahorra una pasada por cada novedad).
+ */
+export function entregado(timbre, r, texto) {
+  if (timbre && r?.modo === 'timbre' && r.version != null && !RE_RECORTADA.test(texto)) timbre.visto = r.version;
+}

package/lib/firestore.mjs

@@ -0,0 +1,181 @@
+// Cliente REST mínimo de Firestore, con el idToken de la cuenta conectada (la de la persona).
+// Las reglas de seguridad se aplican igual que en la web: el MCP no tiene privilegios.
+
+// ── conversión de valores ────────────────────────────────────────────────────
+export function aValor(v) {
+  if (v === null || v === undefined) return { nullValue: null };
+  if (v instanceof Date) return { timestampValue: v.toISOString() };
+  if (typeof v === 'string') return { stringValue: v };
+  if (typeof v === 'boolean') return { booleanValue: v };
+  if (typeof v === 'number') return Number.isInteger(v) ? { integerValue: String(v) } : { doubleValue: v };
+  if (Array.isArray(v)) return { arrayValue: { values: v.map(aValor) } };
+  if (typeof v === 'object') {
+    if (v.__timestamp) return { timestampValue: v.__timestamp };
+    return { mapValue: { fields: aCampos(v) } };
+  }
+  throw new Error(`tipo no soportado: ${typeof v}`);
+}
+
+export function aCampos(obj) {
+  const fields = {};
+  for (const [k, v] of Object.entries(obj)) fields[k] = aValor(v);
+  return fields;
+}
+
+export function deValor(v) {
+  if (!v || 'nullValue' in v) return null;
+  if ('stringValue' in v) return v.stringValue;
+  if ('integerValue' in v) return Number(v.integerValue);
+  if ('doubleValue' in v) return Number(v.doubleValue);
+  if ('booleanValue' in v) return v.booleanValue;
+  if ('timestampValue' in v) return v.timestampValue; // RFC 3339, se compara tal cual
+  if ('mapValue' in v) return deCampos(v.mapValue.fields || {});
+  if ('arrayValue' in v) return (v.arrayValue.values || []).map(deValor);
+  if ('referenceValue' in v) return v.referenceValue;
+  return null;
+}
+
+export function deCampos(fields = {}) {
+  const o = {};
+  for (const [k, v] of Object.entries(fields)) o[k] = deValor(v);
+  return o;
+}
+
+export function deDocumento(doc) {
+  if (!doc?.name) return null;
+  return { id: doc.name.split('/').pop(), ruta: doc.name, ...deCampos(doc.fields) };
+}
+
+// ── errores ──────────────────────────────────────────────────────────────────
+export class ErrorFirestore extends Error {
+  constructor(status, cuerpo) {
+    const msg = cuerpo?.error?.message || cuerpo?.[0]?.error?.message || `HTTP ${status}`;
+    super(msg);
+    this.status = status;
+    this.estado = cuerpo?.error?.status || cuerpo?.[0]?.error?.status || null;
+  }
+  get negado() { return this.status === 403 || this.estado === 'PERMISSION_DENIED'; }
+  get noExiste() { return this.status === 404 || this.estado === 'NOT_FOUND'; }
+  get yaExiste() { return this.status === 409 || this.estado === 'ALREADY_EXISTS'; }
+}
+
+// ── cliente ──────────────────────────────────────────────────────────────────
+export const TIMEOUT_MS = 20 * 1000;
+
+export class Firestore {
+  constructor(config, sesion, { fetch: f = globalThis.fetch } = {}) {
+    this.config = config;
+    this.sesion = sesion;
+    this.fetch = f;
+    const raiz = config.emuladorFirestore ? `http://${config.emuladorFirestore}` : 'https://firestore.googleapis.com';
+    this.db = `projects/${config.projectId}/databases/(default)`;
+    this.base = `${raiz}/v1/${this.db}`;
+  }
+
+  nombre(ruta) {
+    return `${this.db}/documents/${ruta}`;
+  }
+
+  /** Una petición con tope de tiempo; `signal` (opcional) la cancela antes, p. ej. si el agente cancela la espera. */
+  async _pedir(metodo, url, cuerpo, { reintento = true, signal } = {}) {
+    const token = await this.sesion.token();
+    const senales = [AbortSignal.timeout(TIMEOUT_MS), signal].filter(Boolean);
+    let r;
+    try {
+      r = await this.fetch(url, {
+        method: metodo,
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: cuerpo === undefined ? undefined : JSON.stringify(cuerpo),
+        signal: senales.length > 1 ? AbortSignal.any(senales) : senales[0],
+      });
+    } catch (e) {
+      if (e?.name === 'TimeoutError') throw new Error(`Firestore no respondió en ${TIMEOUT_MS / 1000} s`);
+      throw e;
+    }
+    if (r.status === 401 && reintento) {
+      await this.sesion.renovar();
+      return this._pedir(metodo, url, cuerpo, { reintento: false, signal });
+    }
+    const d = await r.json().catch(() => ({}));
+    if (!r.ok) throw new ErrorFirestore(r.status, d);
+    return d;
+  }
+
+  /** Lee un documento; null si no existe. */
+  async leer(ruta) {
+    try {
+      return deDocumento(await this._pedir('GET', `${this.base}/documents/${ruta}`));
+    } catch (e) {
+      if (e instanceof ErrorFirestore && e.noExiste) return null;
+      throw e;
+    }
+  }
+
+  /**
+   * Arma una escritura para :commit (para poder usar la hora del servidor).
+   * opciones: { crear: true } exige que no exista; { existe: true } exige que exista;
+   * mascara: [campos] actualiza solo esos; horaServidor: [campos] = REQUEST_TIME;
+   * agregar / quitar: { campo: [valores] } = appendMissingElements / removeAllFromArray (atómico en el servidor:
+   * dos puentes que agregan a la vez no se pisan).
+   */
+  escritura(ruta, datos, { crear = false, existe = false, mascara = null, horaServidor = [], agregar = null, quitar = null } = {}) {
+    const write = { update: { name: this.nombre(ruta), fields: aCampos(datos) } };
+    if (mascara) write.updateMask = { fieldPaths: mascara.map(campoRuta) };
+    const transformaciones = [
+      ...horaServidor.map((c) => ({ fieldPath: campoRuta(c), setToServerValue: 'REQUEST_TIME' })),
+      ...Object.entries(agregar ?? {}).map(([c, v]) => ({ fieldPath: campoRuta(c), appendMissingElements: { values: v.map(aValor) } })),
+      ...Object.entries(quitar ?? {}).map(([c, v]) => ({ fieldPath: campoRuta(c), removeAllFromArray: { values: v.map(aValor) } })),
+    ];
+    if (transformaciones.length) write.updateTransforms = transformaciones;
+    if (crear) write.currentDocument = { exists: false };
+    else if (existe) write.currentDocument = { exists: true };
+    return write;
+  }
+
+  /** Escribe un documento con :commit. Opciones: las de `escritura`. */
+  async escribir(ruta, datos, opciones = {}) {
+    return this.escribirVarios([{ ruta, datos, opciones }]);
+  }
+
+  /**
+   * Varias escrituras en UN :commit: o se aplican todas o ninguna (si una falla, las reglas o una
+   * precondición, no se escribe nada). Comparten el mismo REQUEST_TIME.
+   * @param {{ ruta: string, datos: object, opciones?: object }[]} escrituras
+   */
+  async escribirVarios(escrituras) {
+    if (!escrituras.length) return null;
+    const writes = escrituras.map((e) => this.escritura(e.ruta, e.datos, e.opciones));
+    const d = await this._pedir('POST', `${this.base}/documents:commit`, { writes });
+    return d.commitTime;
+  }
+
+  async borrar(ruta) {
+    await this._pedir('DELETE', `${this.base}/documents/${ruta}`);
+  }
+
+  /** runQuery sobre una colección hija de `padre` (ruta de documento o '' para la raíz). */
+  async consultar(padre, consulta, { signal } = {}) {
+    const url = padre ? `${this.base}/documents/${padre}:runQuery` : `${this.base}/documents:runQuery`;
+    const filas = await this._pedir('POST', url, { structuredQuery: consulta }, { signal });
+    return filas.filter((f) => f.document).map((f) => deDocumento(f.document));
+  }
+
+  /** Lee varios documentos de una vez; omite los que no existen. */
+  async leerVarios(rutas, { signal } = {}) {
+    if (!rutas.length) return [];
+    const filas = await this._pedir('POST', `${this.base}/documents:batchGet`, {
+      documents: rutas.map((r) => this.nombre(r)),
+    }, { signal });
+    return filas.filter((f) => f.found).map((f) => deDocumento(f.found));
+  }
+}
+
+/** Las rutas de campo con caracteres fuera de [A-Za-z_0-9] van entre comillas invertidas. */
+export function campoRuta(campo) {
+  return campo.split('.').map((p) => (/^[A-Za-z_][A-Za-z_0-9]*$/.test(p) ? p : `\`${p.replace(/`/g, '\\`')}\``)).join('.');
+}
+
+// ayudas para armar consultas
+export const filtro = (campo, op, valor) => ({ fieldFilter: { field: { fieldPath: campo }, op, value: aValor(valor) } });
+export const y = (...filtros) => (filtros.length === 1 ? filtros[0] : { compositeFilter: { op: 'AND', filters: filtros } });
+export const marcaDeTiempo = (iso) => ({ __timestamp: iso });