@nyx5/nyx5 0.6.0 → 0.8.0

package/src/correo/ideas.js

@@ -0,0 +1,154 @@
+// Nyx5/1 — ideas@: el buzón automático de vacaciones. RECIBE, GUARDA y CONFIRMA. NUNCA EJECUTA.
+//
+// Nació del pedido de Nicholas del 14-sep-2026 (se va un mes): un lugar donde dejar una idea desde
+// el teléfono y saber que quedó anotada, sin que nadie la ejecute ni la interprete. Corre desde el
+// reloj programado de la casa, sin el Mac y sin ningún modelo de lenguaje.
+//
+// Límites, y son DE CÓDIGO, no de configuración:
+//   - Este módulo no importa nada que hable con la API de Anthropic ni con el Libro, y no tiene
+//     `fetch`. Lo único que sabe mandar es la confirmación a quien escribió (`agente.send` una vez,
+//     al `from` del sobre recibido). `test/ideas.test.js` lo comprueba por inspección de la fuente
+//     (lista CERRADA de lo que puede tocar de la estafeta, del almacén y del agente) y espiando las
+//     salidas de la casa durante el tick.
+//   - Sólo registra sobres FIRMADOS de quien está en la lista del buzón. La puerta (`puertaIdeas`,
+//     que `inbound` consulta para este buzón) rechaza al resto ANTES de guardar nada: ni el `intro`
+//     corto ni el aval con fianza que la política general deja pasar (§9) sirven aquí, porque este
+//     buzón no tiene a nadie que los lea. El tick vuelve a mirar la lista por si algo entró por
+//     otra puerta (un correo, un sobre anterior al alta): se cierra sin registrar y sin contestar.
+//   - Cupo diario por remitente en la puerta (revisión adversarial del 14-sep-2026: una dirección
+//     de la lista podía meter 112 MB por minuto en el buzón, que no se borra nunca): 200 ideas y
+//     5 MB por día UTC; lo que sobra rebota con motivo desde la puerta, no desde este módulo.
+//   - El contenido no se guarda aparte: sigue cifrado en el buzón de ideas@. El registro lleva
+//     sólo el número, quién, cuándo, el hash del sobre, el hilo y el proyecto.
+//   - El texto de la confirmación es FIJO (aprobado con el pedido: «registra y confirma, nunca
+//     ejecuta») y vive en un solo lugar: `CONFIRMACION`.
+import { parseAddress } from './resolver.js';
+import { sha256hex, canonical } from '../nucleo/crypto.js';
+import { proyectoDe, rolDe } from './politica.js';
+
+export const LOCAL = 'ideas';
+export const NS = 'ideas';           // nyx5_kv: `_n` (contador), `n:<000001>` (registro), `sobre:<id>` (idempotencia)
+export const NS_CUPO = 'ideas-cupo'; // nyx5_kv: `<from>:<día>:n` y `<from>:<día>:bytes`, vencen al día siguiente
+export const VIA = 'ideas';          // custody.via de la tarjeta: la casa firma y descifra en su nombre
+export const CUPO_DIARIO = { ideas: 200, bytes: 5 * 1024 * 1024 };
+export const PAGINA = 1000;          // GET /ideas devuelve hasta esto por página, con `next`
+const SISTEMA = new Set(['postmaster', 'libro', 'verifica', 'tareas']);
+const TURNO_MS = 15 * 60_000;
+const DIA_MS = 24 * 3600 * 1000;
+
+export const idDeIdea = (n) => `IDEA-${String(n).padStart(3, '0')}`;
+const claveDe = (n) => `n:${String(n).padStart(6, '0')}`;
+// «2026-09-15 10:22» a partir de una fecha ISO (siempre UTC).
+export const fechaCorta = (isoStr) => String(isoStr).slice(0, 16).replace('T', ' ');
+export const CONFIRMACION = (id, at) => `Saved as ${id} on ${fechaCorta(at)} UTC. Nothing was executed: this mailbox only records and confirms. Nicholas reads it when he is back.`;
+
+const minus = (x) => String(x || '').toLowerCase();
+function enLista(lista, from) {
+  const f = minus(from);
+  let dominio = ''; try { dominio = parseAddress(f).domain; } catch { dominio = ''; }
+  return lista.some((x) => x === f || (dominio && x === dominio));
+}
+
+// La puerta de ideas@, consultada por `inbound` DESPUÉS de la política general y ANTES de guardar.
+// Devuelve null si el sobre puede entrar, o `{ code, reason }` para rechazarlo (el rebote lo hace la
+// estafeta emisora, como con cualquier rechazo de la puerta: no es una salida de este módulo).
+// Rechaza (403, permanente) a quien no está en la lista y a quien agotó su cupo del día: un
+// rechazo transitorio (429) dejaría los sobres reintentando en la cola de la otra casa un día entero.
+// Lo que NO cubre: el cupo se cuenta al aceptar en la puerta, así que dos casas emisoras que
+// entreguen a la vez pueden pasarse por uno; y sólo protege el buzón de ideas@, no el resto de la casa.
+export async function puertaIdeas(est, env, rec, { cupo = CUPO_DIARIO, nowMs = Date.now() } = {}) {
+  const lista = (rec?.inbox?.allowlist || []).map(minus);
+  if (!enLista(lista, env.from)) return { code: 403, reason: 'the ideas mailbox records only signed envelopes from its list: not recorded' };
+  if (!est.store.kvIncrement) return null;
+  const dia = new Date(nowMs).toISOString().slice(0, 10);
+  const vence = (Math.floor(nowMs / DIA_MS) + 2) * DIA_MS;
+  const clave = `${minus(env.from)}:${dia}`;
+  const bytes = Buffer.byteLength(JSON.stringify(env));
+  // Se suma ANTES de comparar: con dos relojes contando a la vez, el que se pasa cierra el día.
+  const n = await est.store.kvIncrement(NS_CUPO, `${clave}:n`, vence, nowMs);
+  const total = await est.store.kvIncrement(NS_CUPO, `${clave}:bytes`, vence, nowMs, bytes);
+  if (n > cupo.ideas || total > cupo.bytes) return { code: 403, reason: `daily limit of the ideas mailbox reached for this sender (${cupo.ideas} ideas or ${Math.round(cupo.bytes / 1024 / 1024)} MB per UTC day): not recorded` };
+  return null;
+}
+
+// El registro ordenado por número, para GET /ideas: hasta `limit` registros con número > `after`.
+export async function listarIdeas(est, { after = 0, limit = PAGINA } = {}) {
+  const filas = await est.store.kvList(NS, { prefix: 'n:', after: after > 0 ? claveDe(after) : undefined, limit });
+  return filas.map((f) => f.doc).sort((a, b) => a.n - b.n);
+}
+// Lo que contesta GET /ideas: `total` es el último número asignado (puede superar a los registros
+// si un reloj cayó entre asignar el número y escribir el registro), `next` es el número desde el
+// que sigue la página siguiente, o null si ésta es la última.
+export async function paginaDeIdeas(est, { after = 0 } = {}) {
+  const ideas = await listarIdeas(est, { after, limit: PAGINA });
+  const total = Number(await est.store.kvGet(NS, '_n')) || 0;
+  return { total, count: ideas.length, ideas, next: ideas.length === PAGINA ? ideas[ideas.length - 1].n : null };
+}
+
+// Un tick: cada sobre pendiente del buzón se registra (número correlativo durable) y se confirma.
+// Devuelve cuántas ideas registró. Dos relojes sobre el mismo almacén no repiten número ni
+// confirmación: un turno por sobre (`kvPutIfAbsent`) y un número por sobre (`sobre:<id>`).
+// `maxPorTick` acota las ideas registradas por pasada; `maxDescartesPorTick`, lo que se cierra sin
+// registrar (correo sin firma, rebotes del postmaster, algo anterior al alta): un buzón lleno de
+// eso no puede comerse el minuto del reloj, y tampoco puede dejar sin turno a las ideas de verdad
+// (son cupos separados).
+export async function atenderIdeas(est, { maxPorTick = 20, maxDescartesPorTick = 200 } = {}) {
+  if (!est.ideas?.enabled || !est.store.kvIncrement) return 0;
+  const rec = await est.store.getAgent(LOCAL);
+  if (!rec || rec.revoked || rec.custody?.via !== VIA) return 0;
+  const lista = (rec.inbox?.allowlist || []).map(minus);
+  const propia = `${LOCAL}@${est.domain}`;
+  let registradas = 0;
+  let vistos = 0, descartes = 0;
+  for (const m of await est.store.listMail(LOCAL)) {
+    if (vistos >= maxPorTick && descartes >= maxDescartesPorTick) break;
+    const e = m.envelope || {};
+    let de; try { de = parseAddress(e.from); } catch { continue; }
+    // Lo que manda la casa (un rebote, un recibo) o el propio buzón no es una idea: se cierra y sigue.
+    const deSistema = (de.domain === est.domain && SISTEMA.has(de.local)) || e.from === propia || e.type === 'receipt';
+    // Sin firma (un correo) o fuera de la lista (algo que entró antes del alta o por otra puerta): se
+    // cierra sin registrar y sin contestar. Contestarle a un desconocido sería la salida que este
+    // buzón no tiene.
+    const ajeno = !e.signature || m.from_verified === false || !enLista(lista, e.from);
+    if (deSistema || ajeno) {
+      if (descartes >= maxDescartesPorTick) continue;
+      descartes++;
+      if (!deSistema) est.log(`ideas@: sobre ${e.id} de ${e.from} descartado (${!e.signature || m.from_verified === false ? 'sin firma' : 'fuera de la lista'})`);
+      await est.store.ackMail(LOCAL, e.id);
+      continue;
+    }
+    if (vistos >= maxPorTick) continue;
+    vistos++;
+    if (!(await est.store.kvPutIfAbsent('ideas-turno', e.id, { at: new Date().toISOString() }, Date.now() + TURNO_MS))) continue;
+    try {
+      const agente = await est.agenteDeBoveda(LOCAL);
+      if (!agente) throw new Error('la bóveda no tiene la llave de ideas@');
+      // Un número por sobre: si un tick anterior asignó número y no llegó a confirmar, se reutiliza.
+      let n = Number((await est.store.kvGet(NS, `sobre:${e.id}`))?.n) || 0;
+      if (!n) {
+        n = await est.store.kvIncrement(NS, '_n');
+        await est.store.kvPut(NS, `sobre:${e.id}`, { n });
+      }
+      // El registro se escribe si no está, aunque el número ya estuviera asignado: un reloj que cayó
+      // entre asignar el número y escribir el registro no puede dejar una idea confirmada y sin
+      // registro (revisión adversarial del 14-sep-2026). No depende del contenido: si el sobre no se
+      // puede abrir, se registra igual por su hash.
+      let registro = await est.store.kvGet(NS, claveDe(n));
+      if (!registro) {
+        let abierto = false;
+        try { await agente.open(e); abierto = true; } catch { abierto = false; }
+        registro = { n, id: idDeIdea(n), id_sobre: e.id, from: e.from, at: new Date().toISOString(), sha256_sobre: sha256hex(canonical(e)), thread: e.thread || e.id, project: proyectoDe(e), role: rolDe(e), opened: abierto };
+        await est.store.kvPut(NS, claveDe(n), registro);
+      }
+      // La ÚNICA salida de este módulo: la confirmación a quien escribió, en su hilo y su proyecto.
+      await agente.send({ to: e.from, body: CONFIRMACION(registro.id, registro.at), thread: e.thread || e.id, inReplyTo: e.id, project: registro.project || undefined, role: registro.role || undefined });
+      await est.store.ackMail(LOCAL, e.id);
+      registradas++;
+      await est._evento('idea_saved', e.from, { idea: registro.id, sobre: e.id });
+    } catch (err) {
+      // El turno queda tomado 15 minutos y se reintenta; el número, si ya salió, se conserva.
+      est.log(`ideas@: ${e.id} no se pudo confirmar: ${err.message}`);
+    }
+  }
+  return registradas;
+}

package/src/correo/indice.js

@@ -0,0 +1,178 @@
+// Nyx5/1 — búsqueda del índice federado con reputación y precio (NX-302).
+//
+// UNA definición para los dos almacenes: qué columnas se extraen de una tarjeta, cómo se
+// codifica el cursor, qué filtros se aceptan y cómo se pagina. FileStore usa `buscarEnMemoria`
+// tal cual; D1Store traduce las mismas reglas a SQL. Si las dos implementaciones divergen, el
+// test de paginación (test/busqueda.test.js) corre sobre ambas y lo dice.
+//
+// Orden: (puntaje DESC, los sin puntaje al FINAL, dirección ASC). Cursor opaco = base64url de
+// JSON { s, a, g }: el puntaje y la dirección de la última fila servida, y la GENERACIÓN del
+// índice en la que empezó el recorrido. Nunca un offset: un offset sobre un conjunto que cambia
+// entre páginas salta o repite filas (trampa «ventana horneada e isla»).
+//
+// Por qué la generación: el puntaje CAMBIA con cada rastreo, y un cursor por (puntaje,
+// dirección) sobre un puntaje que se mueve repite al que bajó y se salta al que subió. Cada
+// fila guarda, además del puntaje actual, un historial corto de sus cambios: `hist` =
+// [{ g, s }] (generación en que el puntaje pasó a valer s), los últimos HIST_MAX cambios, y
+// `first_gen`, la generación en que la dirección entró al índice. Un recorrido que empezó en
+// la generación g ordena cada fila por el puntaje que tenía en g: la última entrada de `hist`
+// con g' <= g. Si esa entrada ya se descartó (más de HIST_MAX cambios desde que empezó el
+// recorrido), el puntaje congelado no existe: el recorrido se declara caduco (410) y quien
+// recorre vuelve a empezar; nunca se sirve una página en silencio con otro orden.
+// Lo que NO cubre: un agente que ENTRA al índice después de empezar el recorrido va al final
+// (clave nula) y se ve sólo si el recorrido no pasó ya por los nulos; uno que SALE deja de
+// verse; y los filtros de etiqueta/idioma/precio miran la fila ACTUAL (quien cambió de ficha a
+// mitad del recorrido entra o sale del conjunto según su ficha de hoy).
+
+import { puntajeArbitrado } from '../libro/libro.js';
+
+const fallo = (status, message) => Object.assign(new Error(message), { status });
+
+// ---------- columnas que el índice extrae de una tarjeta ----------
+// El precio sale de `profile.services[].price.tokens` (la ficha con servicios la agrega otro
+// frente; aquí sólo se lee si existe). Sin servicios con precio en tokens, `price_min` es null
+// y el agente NO pasa un filtro `price_max`: no anunciar precio no es ser gratis.
+export function precioMinimo(card) {
+  const servicios = card?.profile?.services;
+  if (!Array.isArray(servicios)) return null;
+  const precios = servicios.map((s) => s?.price?.tokens).filter((t) => Number.isInteger(t) && t >= 0);
+  return precios.length ? Math.min(...precios) : null;
+}
+
+export function columnasDeIndice(card) {
+  const tags = Array.isArray(card?.profile?.tags) ? card.profile.tags.filter((t) => typeof t === 'string') : [];
+  const langs = Array.isArray(card?.profile?.languages) ? card.profile.languages.filter((l) => typeof l === 'string').map((l) => l.toLowerCase()) : [];
+  const score = typeof card?._score === 'number' && Number.isFinite(card._score) ? card._score : null;
+  const jobs_done = Number.isInteger(card?._jobs_done) ? card._jobs_done : null;
+  return { tags, langs, price_min: precioMinimo(card), score, jobs_done };
+}
+
+// El puntaje de un agente a partir de su historial público (§21). Sólo cuenta lo arbitrado por
+// `verifica@` de su casa; una casa que no distingue arbitrados (versión anterior) no da puntaje.
+// Devuelve también el motivo cuando no hay puntaje, para que el rastreo cuente su denominador.
+export function puntajeDe(historial) {
+  if (!historial || typeof historial !== 'object') return { score: null, jobs_done: null, motivo: 'sin_historial' };
+  if (!historial.arbitrados || typeof historial.arbitrados !== 'object') return { score: null, jobs_done: null, motivo: 'sin_arbitrados' };
+  const score = puntajeArbitrado(historial.arbitrados);
+  if (score == null) return { score: null, jobs_done: 0, motivo: 'sin_historial' };
+  return { score, jobs_done: Number(historial.arbitrados.liberados?.n) || 0, motivo: null };
+}
+
+// ---------- cursor ----------
+export function codificarCursor({ s, a, g }) {
+  return Buffer.from(JSON.stringify({ s: s ?? null, a, g })).toString('base64url');
+}
+export function decodificarCursor(texto) {
+  const invalido = () => fallo(400, 'invalid cursor: use the next_cursor the index gave you, or none for the first page');
+  if (typeof texto !== 'string' || !/^[A-Za-z0-9_-]{1,600}$/.test(texto)) throw invalido();
+  let c;
+  try { c = JSON.parse(Buffer.from(texto, 'base64url').toString('utf8')); } catch { throw invalido(); }
+  if (!c || typeof c !== 'object' || Array.isArray(c)) throw invalido();
+  if (Object.keys(c).some((k) => !['s', 'a', 'g'].includes(k))) throw invalido();
+  if (!(c.s === null || (typeof c.s === 'number' && Number.isFinite(c.s) && c.s >= 0 && c.s <= 1))) throw invalido();
+  if (typeof c.a !== 'string' || !c.a || c.a.length > 320) throw invalido();
+  if (!Number.isSafeInteger(c.g) || c.g < 0) throw invalido();
+  return c;
+}
+
+// ---------- filtros de la consulta ----------
+// `p` son los parámetros crudos (strings de la URL o valores de la herramienta MCP). Falla con
+// 400 ante lo que no se puede interpretar; `limit` se acota como siempre (nunca fue un 400).
+export const FILTROS = ['q', 'tag', 'lang', 'capability', 'accepts', 'house', 'price_max', 'min_score', 'limit', 'cursor'];
+export function validarFiltros(p = {}) {
+  const vacio = (v) => v == null || v === '';
+  if (!vacio(p.offset)) throw fallo(400, 'offset is not supported: page with cursor (next_cursor of the previous page)');
+  const f = {};
+  for (const k of ['q', 'capability', 'accepts', 'house']) {
+    if (vacio(p[k])) continue;
+    if (typeof p[k] !== 'string' || p[k].length > 200) throw fallo(400, `${k} must be a string of up to 200 characters`);
+    if (k === 'capability' && !/^[a-z0-9_-]{1,64}$/.test(p[k])) throw fallo(400, 'capability must be 1-64 lowercase letters, digits, dashes or underscores');
+    f[k] = k === 'house' ? p[k].toLowerCase() : p[k];
+  }
+  if (!vacio(p.tag)) {
+    if (typeof p.tag !== 'string' || !/^[a-z0-9-]{1,32}$/.test(p.tag)) throw fallo(400, 'tag must be 1-32 lowercase letters, digits and dashes');
+    f.tag = p.tag;
+  }
+  if (!vacio(p.lang)) {
+    const l = String(p.lang).toLowerCase();
+    if (!/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/.test(l)) throw fallo(400, 'lang must be a language tag like "es" or "en-US"');
+    f.lang = l;
+  }
+  if (!vacio(p.price_max)) {
+    const n = Number(p.price_max);
+    if (!Number.isInteger(n) || n < 0) throw fallo(400, 'price_max must be a non-negative integer (tokens)');
+    f.price_max = n;
+  }
+  if (!vacio(p.min_score)) {
+    const n = Number(p.min_score);
+    if (!Number.isFinite(n) || n < 0 || n > 1) throw fallo(400, 'min_score must be a number between 0 and 1');
+    f.min_score = n;
+  }
+  const lim = Number(p.limit);
+  f.limit = Number.isInteger(lim) && lim > 0 ? Math.min(lim, 200) : 50;
+  if (!vacio(p.cursor)) f.cursor = decodificarCursor(p.cursor);
+  return f;
+}
+
+// ---------- filas: historial de puntajes ----------
+export const HIST_MAX = 16;
+// La fila nueva de una tarjeta al reemplazar la casa en la generación `gen`, dada la fila previa
+// de esa dirección (o null si es nueva). Sólo se anota un cambio cuando el puntaje cambia.
+export function filaDeIndice(house, card, gen, previa) {
+  const col = columnasDeIndice(card);
+  const hist = Array.isArray(previa?.hist) ? previa.hist.slice() : [];
+  if (!hist.length || (hist[hist.length - 1].s ?? null) !== col.score) hist.push({ g: gen, s: col.score });
+  return { house, address: card.address, doc: card, ...col, gen, first_gen: previa?.first_gen ?? gen, hist: hist.slice(-HIST_MAX) };
+}
+// Puntaje congelado de una fila para un recorrido que empezó en g. `undefined` = caduco.
+export function claveCongelada(r, g) {
+  if ((r.first_gen ?? 0) > g) return null;
+  const e = (r.hist || []).filter((x) => x.g <= g).at(-1);
+  if (!e) return undefined;
+  return e.s ?? null;
+}
+
+// ---------- la búsqueda, en memoria (FileStore y referencia para D1) ----------
+// `filas`: [{ house, address, doc, tags, langs, price_min, score, jobs_done, gen, first_gen, hist }]
+export function buscarEnMemoria(filas, f) {
+  const gActual = filas.reduce((m, r) => Math.max(m, r.gen || 0), 0);
+  if (f.cursor && f.cursor.g > gActual) throw fallo(400, 'invalid cursor: it names a generation of the index that does not exist');
+  const g = f.cursor ? f.cursor.g : gActual;
+  let sel = filas.filter((r) => filtraFila(r, f)).map((r) => ({ r, k: claveCongelada(r, g) }));
+  if (sel.some((x) => x.k === undefined)) throw fallo(410, CADUCO);
+  if (f.min_score != null) sel = sel.filter((x) => x.k != null && x.k >= f.min_score);
+  const total = sel.length;
+  if (f.cursor) sel = sel.filter((x) => despuesDelCursor(x.k, x.r.address, f.cursor));
+  sel.sort((x, y) => compararFilas(x.k, x.r.address, y.k, y.r.address));
+  const pagina = sel.slice(0, f.limit);
+  const ultima = pagina[pagina.length - 1];
+  const next_cursor = sel.length > f.limit ? codificarCursor({ s: ultima.k, a: ultima.r.address, g }) : null;
+  return { total, agents: pagina.map((x) => x.r.doc), next_cursor };
+}
+export const CADUCO = 'cursor expired: the scores this walk was ordered by are no longer kept by the index; start again without cursor';
+
+export function filtraFila(r, f) {
+  const c = r.doc || {};
+  if (f.house && r.house !== f.house) return false;
+  if (f.capability && !c.capabilities?.[f.capability]) return false;
+  if (f.accepts && !c.capabilities?.accepts?.includes(f.accepts)) return false;
+  if (f.tag && !(r.tags || []).includes(f.tag)) return false;
+  if (f.lang && !(r.langs || []).some((l) => l === f.lang || l.startsWith(`${f.lang}-`))) return false;
+  if (f.price_max != null && !(r.price_min != null && r.price_min <= f.price_max)) return false;
+  if (f.q && !JSON.stringify(c).toLowerCase().includes(String(f.q).toLowerCase())) return false;
+  return true;
+}
+
+// Mismo orden que el SQL: puntaje DESC con nulos al final, dirección ASC (comparación binaria).
+export function compararFilas(kx, ax, ky, ay) {
+  if (kx == null && ky == null) return ax < ay ? -1 : ax > ay ? 1 : 0;
+  if (kx == null) return 1;
+  if (ky == null) return -1;
+  if (kx !== ky) return ky - kx;
+  return ax < ay ? -1 : ax > ay ? 1 : 0;
+}
+
+export function despuesDelCursor(k, address, cur) {
+  if (cur.s == null) return k == null && address > cur.a;
+  return (k != null && k < cur.s) || (k === cur.s && address > cur.a) || k == null;
+}