@nyx5/nyx5 0.6.0 → 0.8.0

package/src/libro/verifica.js

@@ -1,12 +1,15 @@
 // Nyx5/1 — verifica@: el evaluador de referencia de la casa.
 //
-// Tres pruebas DETERMINISTAS y nada más. Sin juicio de modelo, a propósito: un verificador
+// Pruebas DETERMINISTAS y nada más. Sin juicio de modelo, a propósito: un verificador
 // que se equivoca castiga a un inocente y quema la credibilidad del sistema en un día. Si
 // una prueba no puede decidir sola y sin ambigüedad, este verificador no la acepta.
 //
 //   http_status  GET a una URL -> el código es el esperado (200 por defecto)
 //   sha256       el cuerpo de una URL (o el texto entregado) hashea a lo declarado
-//   json_path    un campo de un JSON servido en una URL vale exactamente lo esperado
+//   json_path    un campo de un JSON servido en una URL vale exactamente lo esperado, o existe
+//   regex        el cuerpo de una URL (primer MB) casa con una expresión regular acotada
+//   size         el cuerpo de una URL pesa a lo sumo / al menos tantos bytes
+//   header       una cabecera de la respuesta vale exactamente lo esperado
 //   exit_0       un comando termina con código 0        [solo fuera del edge: necesita shell]
 //
 // El veredicto es una función pura de (prueba, mundo): dos corridas con el mismo mundo dan
@@ -14,7 +17,7 @@
 
 import { sha256hex, canonical } from '../nucleo/crypto.js';
 
-export const PRUEBAS = ['http_status', 'sha256', 'json_path', 'exit_0'];
+export const PRUEBAS = ['http_status', 'sha256', 'json_path', 'regex', 'size', 'header', 'exit_0'];
 // En el edge no hay shell. Dos señales, porque una sola engañaba:
 //   - con nodejs_compat, Workers expone `process` Y deja importar node:child_process, así que
 //     ni la variable ni el import distinguen el runtime; la casa anunciaba exit_0 y luego no
@@ -32,38 +35,145 @@ const enWorkers = typeof navigator !== 'undefined' && /Cloudflare-Workers/i.test
 export const conShell = !enWorkers && typeof process !== 'undefined' && !!process?.versions?.node;
 export const pruebasDisponibles = () => (conShell ? PRUEBAS : PRUEBAS.filter((p) => p !== 'exit_0'));
 
+// Tope de lo que se descarga para mirar un cuerpo (regex, size). Un cuerpo más grande no se lee
+// entero: el verificador no es un espejo, y un servidor hostil no puede hacerle tragar gigas.
+export const CUERPO_MAX = 1_048_576;
+// regex mira menos: 256 KB y líneas de 2 KB, porque su costo depende del patrón (ver patronSeguro).
+export const REGEX_MAX = 262_144;
+export const REGEX_LINEA = 2048;
+export const PATRON_MAX = 256;
+const BANDERAS = /^[imsu]{0,4}$/;
+
 const recorta = (s, n = 300) => (typeof s === 'string' && s.length > n ? `${s.slice(0, n)}…` : s);
+// Sólo https y nunca hacia adentro: verifica@ hace la petición desde la casa, y una URL que apunte
+// a loopback, a una red privada o a la metadata de la nube convertiría a la casa en un diputado
+// confundido (revisión del 14-sep-2026). Los redirects no se siguen por la misma razón.
+const HOST_PRIVADO = /^(localhost|.*\.localhost|.*\.local|.*\.internal|0\.0\.0\.0|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|169\.254\.\d+\.\d+|\[?::1\]?|\[?f[cd][0-9a-f]{2}:.*|\[?fe80:.*|metadata\.google\.internal)$/i;
+// `privados: true` sólo en pruebas locales (la casa lo decide en su config, nunca el contrato).
+let permitirPrivados = false;
+const esHttps = (u) => { try { const x = new URL(String(u || '')); return x.protocol === 'https:' && (permitirPrivados || !HOST_PRIVADO.test(x.hostname)) && !x.username && !x.password; } catch { return false; } };
+const metodoDe = (p) => { const m = String(p.method || 'GET').toUpperCase(); return m === 'GET' || m === 'HEAD' ? m : null; };
+
+// Lee el cuerpo de una respuesta hasta `max` bytes y dice si había más. Con un cuerpo en flujo
+// (fetch real) corta la descarga; con un doble de pruebas que sólo tiene `text()` recorta lo leído.
+async function leerCuerpo(res, max) {
+  if (res.body && typeof res.body.getReader === 'function') {
+    const lector = res.body.getReader();
+    const partes = []; let bytes = 0; let truncado = false;
+    for (;;) {
+      const { done, value } = await lector.read();
+      if (done) break;
+      const sobra = bytes + value.byteLength - max;
+      if (sobra > 0) { partes.push(value.subarray(0, value.byteLength - sobra)); bytes = max; truncado = true; try { await lector.cancel(); } catch { /* ya se leyó lo que se necesitaba */ } break; }
+      partes.push(value); bytes += value.byteLength;
+    }
+    const buf = new Uint8Array(bytes); let o = 0;
+    for (const p of partes) { buf.set(p, o); o += p.byteLength; }
+    return { texto: new TextDecoder().decode(buf), bytes, truncado };
+  }
+  const texto = String(await res.text());
+  const codificado = new TextEncoder().encode(texto);
+  if (codificado.byteLength > max) return { texto: new TextDecoder().decode(codificado.subarray(0, max)), bytes: max, truncado: true };
+  return { texto, bytes: codificado.byteLength, truncado: false };
+}
+
+// Camino literal de json_path: `a.b.0.c` o `a.b[0].c`. Sin comodines ni expresiones. Devuelve
+// la lista de segmentos, o null si la forma no es ésa.
+export function segmentosDe(path) {
+  if (typeof path !== 'string' || !/^[^.[\]]+(\[\d+\])*(\.[^.[\]]+(\[\d+\])*)*$/.test(path)) return null;
+  return path.split('.').flatMap((s) => { const [cabeza, ...idx] = s.split('['); return [cabeza, ...idx.map((i) => i.slice(0, -1))]; });
+}
+
+// Lo que se acepta como patrón de `regex`. Un motor de expresiones regulares con retroceso puede
+// tardar tiempo exponencial con ciertas formas, y el verificador no puede interrumpir una prueba a
+// medias: el edge lo mataría por CPU y el contrato quedaría indeciso para siempre. En vez de medir
+// el tiempo se RESTRINGE la sintaxis a lo que no lo sufre:
+//   - sin referencias hacia atrás (\1, \k<n>);
+//   - ningún cuantificador sobre un grupo que por dentro tiene otro cuantificador o una
+//     alternancia: (a+)+, (a|ab)*, (?:x*)? quedan fuera; [ab]+ y (ab)+ entran;
+//   - largo máximo PATRON_MAX y banderas sólo i, m, s, u.
+// Lo que NO cubre: no es una prueba formal de linealidad; deja fuera patrones inocentes con esa
+// forma (falso positivo visible al cotizar, nunca silencioso) y no acota patrones largos sin
+// grupos, que sobre 1 MB siguen siendo lineales.
+export function patronSeguro(pattern, flags = '') {
+  if (typeof pattern !== 'string' || !pattern.length) return { ok: false, razon: 'regex needs a non-empty pattern' };
+  if (pattern.length > PATRON_MAX) return { ok: false, razon: `pattern is longer than ${PATRON_MAX} characters` };
+  if (typeof flags !== 'string' || !BANDERAS.test(flags)) return { ok: false, razon: 'flags may only combine i, m, s and u' };
+  if (/\\[1-9]|\\k</.test(pattern)) return { ok: false, razon: 'backreferences are not accepted: they can backtrack exponentially' };
+  const pila = []; let enClase = false;
+  const cuant = (ch) => ch !== undefined && /[*+?{]/.test(ch);
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '\\') { i++; continue; }
+    if (enClase) { if (c === ']') enClase = false; continue; }
+    if (c === '[') { enClase = true; continue; }
+    if (c === '(') {
+      pila.push({ cuant: false, alt: false });
+      // Prefijos de grupo: (?:  (?=  (?!  (?<=  (?<!  (?<nombre>. El `?` de ahí no es un cuantificador.
+      if (pattern[i + 1] === '?') { i += 2; if (pattern[i] === '<' && !/[=!]/.test(pattern[i + 1] || '')) i = pattern.indexOf('>', i); if (i < 0) return { ok: false, razon: 'malformed group' }; }
+      continue;
+    }
+    if (c === ')') {
+      const g = pila.pop();
+      if (!g) return { ok: false, razon: 'unbalanced parentheses' };
+      const sigue = cuant(pattern[i + 1]);
+      if (sigue && (g.cuant || g.alt)) return { ok: false, razon: 'a quantifier over a group that contains a quantifier or an alternation is not accepted (it can backtrack exponentially); use a character class like [ab]+' };
+      if (pila.length) { const p = pila.at(-1); p.cuant = p.cuant || g.cuant || sigue; p.alt = p.alt || g.alt; }
+      continue;
+    }
+    if (c === '|') { if (pila.length) pila.at(-1).alt = true; continue; }
+    if (cuant(c) && pila.length) pila.at(-1).cuant = true;
+  }
+  if (pila.length) return { ok: false, razon: 'unbalanced parentheses' };
+  // Revisión del 14-sep-2026 (ALTO probado): `a*a*b` o `\\w*\\w*x` pasaban el guardia de grupos y
+  // colgaban más de 20 s sobre 1 MB: dos cuantificadores hermanos sobre lo mismo son polinómicos,
+  // y en el edge eso congela la verificación de toda la casa. Regla acotada por CONSTRUCCIÓN, no
+  // por medición: un solo cuantificador sin tope en todo el patrón, los con tope hasta {n,64}, y no
+  // más de cuatro cuantificadores en total. Además el texto se prueba línea por línea (ver regex).
+  const sinClases = pattern.replace(/\\./g, '__').replace(/\[[^\]]*\]/g, 'C');
+  const sinTope = (sinClases.match(/[*+]|\{\d+,\}/g) || []).length;
+  const conTope = [...sinClases.matchAll(/\{(\d+)(?:,(\d+))?\}/g)].filter((m) => m[2] !== undefined || !m[0].endsWith(',}'));
+  if (sinTope > 1) return { ok: false, razon: 'only one unbounded quantifier (*, + or {n,}) per pattern: two of them over overlapping text backtrack polynomially over a large body' };
+  if (conTope.some((m) => Number(m[2] ?? m[1]) > 64)) return { ok: false, razon: 'bounded quantifiers may repeat at most 64 times' };
+  if (sinTope + conTope.length + (sinClases.match(/\?/g) || []).length > 4) return { ok: false, razon: 'at most four quantifiers per pattern' };
+  try { new RegExp(pattern, flags); } catch (e) { return { ok: false, razon: `invalid pattern: ${e.message}` }; }
+  return { ok: true };
+}
 
 /**
  * Corre UNA prueba y devuelve un veredicto con su evidencia.
- * @returns {Promise<{pasa:boolean, prueba:string, razon:string, evidencia:object}>}
+ * @returns {Promise<{pasa:boolean, prueba:string, razon:string, evidencia:object, indeciso?:boolean}>}
  */
-export async function correrPrueba(prueba, { fetchImpl = globalThis.fetch, timeoutMs = 10_000, entregado = null, entregadoSha256 = null } = {}) {
+export async function correrPrueba(prueba, { fetchImpl = globalThis.fetch, timeoutMs = 10_000, entregado = null, entregadoSha256 = null, privados = false } = {}) {
+  permitirPrivados = privados === true;
   const tipo = prueba?.type;
   if (!PRUEBAS.includes(tipo)) {
     return { pasa: false, prueba: tipo || '(sin tipo)', razon: `prueba desconocida: ${tipo}. Las que este verificador acepta: ${pruebasDisponibles().join(', ')}`, evidencia: {} };
   }
   if (tipo === 'exit_0' && !conShell) {
-    return { pasa: false, prueba: tipo, razon: 'este verificador corre en el edge y no tiene shell; usa http_status o sha256', evidencia: {} };
+    return { pasa: false, prueba: tipo, razon: 'este verificador corre en el edge y no tiene shell; usa http_status, sha256, json_path, regex, size o header', evidencia: {} };
   }
+  const falla = (razon, evidencia = {}) => ({ pasa: false, prueba: tipo, razon, evidencia });
+  // Un 52x no lo emite el servidor que se está comprobando: lo emite la infraestructura que
+  // hay delante cuando no logra llegar. Tratarlo como "la afirmación es falsa" castiga al
+  // agente por una red que no controla — pasó de verdad: una tarea sembrada apuntaba a la
+  // propia casa, el borde devolvió 522 y el trabajo se devolvió como si fuera mentira.
+  const delBorde = (res) => (res.status >= 520 && res.status <= 527
+    ? { pasa: false, indeciso: true, prueba: tipo, razon: `could not reach ${prueba.url} (${res.status} from the edge, not from the server being checked)`, evidencia: { url: prueba.url, status: res.status } }
+    : null);
   try {
     if (tipo === 'http_status') {
       const esperado = Number(prueba.expect ?? 200);
-      if (!/^https:\/\//.test(prueba.url || '')) return { pasa: false, prueba: tipo, razon: 'la URL a verificar debe ser https', evidencia: { url: prueba.url } };
-      const res = await fetchImpl(prueba.url, { method: prueba.method || 'GET', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
-      // Un 52x no lo emite el servidor que se está comprobando: lo emite la infraestructura que
-      // hay delante cuando no logra llegar. Tratarlo como "la afirmación es falsa" castiga al
-      // agente por una red que no controla — pasó de verdad: una tarea sembrada apuntaba a la
-      // propia casa, el borde devolvió 522 y el trabajo se devolvió como si fuera mentira.
-      if (res.status >= 520 && res.status <= 527) {
-        return { pasa: false, indeciso: true, prueba: tipo, razon: `could not reach ${prueba.url} (${res.status} from the edge, not from the server being checked)`, evidencia: { url: prueba.url, status: res.status } };
-      }
+      if (!esHttps(prueba.url)) return falla('the URL to verify must be https and public', { url: prueba.url });
+      if (!metodoDe(prueba)) return falla(`method must be GET or HEAD, not ${String(prueba.method)}`, { url: prueba.url });
+      const res = await fetchImpl(prueba.url, { method: metodoDe(prueba), redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+      const borde = delBorde(res); if (borde) return borde;
       const pasa = res.status === esperado;
       return { pasa, prueba: tipo, razon: pasa ? `${prueba.url} responded ${res.status}` : `${prueba.url} responded ${res.status}, expected ${esperado}`, evidencia: { url: prueba.url, status: res.status, expect: esperado } };
     }
     if (tipo === 'sha256') {
       const esperado = String(prueba.expect || '').toLowerCase();
-      if (!/^[0-9a-f]{64}$/.test(esperado)) return { pasa: false, prueba: tipo, razon: 'expect debe ser un sha256 en hexadecimal (64 caracteres)', evidencia: {} };
+      if (!/^[0-9a-f]{64}$/.test(esperado)) return falla('expect debe ser un sha256 en hexadecimal (64 caracteres)');
       // El agente pudo declarar el hash de su resultado al entregar (deliver.evidence_sha256).
       // Ese es el caso normal cuando el trabajo no vive en una URL: se compara lo que DIJO
       // contra lo que la tarea exige. Si además hay url, gana lo que se puede descargar.
@@ -74,9 +184,10 @@ export async function correrPrueba(prueba, { fetchImpl = globalThis.fetch, timeo
       }
       let texto = entregado;
       if (prueba.url) {
-        if (!/^https:\/\//.test(prueba.url)) return { pasa: false, prueba: tipo, razon: 'la URL a verificar debe ser https', evidencia: { url: prueba.url } };
-        const res = await fetchImpl(prueba.url, { signal: AbortSignal.timeout(timeoutMs) });
-        if (!res.ok) return { pasa: false, prueba: tipo, razon: `${prueba.url} respondió ${res.status}: no hay qué hashear`, evidencia: { url: prueba.url, status: res.status } };
+        if (!esHttps(prueba.url)) return falla('la URL a verificar debe ser https', { url: prueba.url });
+        const res = await fetchImpl(prueba.url, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        const borde = delBorde(res); if (borde) return borde;
+        if (!res.ok) return falla(`${prueba.url} respondió ${res.status}: no hay qué hashear`, { url: prueba.url, status: res.status });
         texto = await res.text();
       }
       if (texto == null) return { pasa: false, prueba: tipo, razon: 'no hay contenido que hashear: la prueba necesita una url, o la entrega debe declarar evidence_sha256', evidencia: {}, indeciso: true };
@@ -85,34 +196,96 @@ export async function correrPrueba(prueba, { fetchImpl = globalThis.fetch, timeo
       return { pasa, prueba: tipo, razon: pasa ? `el hash coincide (${visto.slice(0, 12)}…)` : `el hash no coincide: se vio ${visto.slice(0, 12)}…, se esperaba ${esperado.slice(0, 12)}…`, evidencia: { sha256: visto, expect: esperado, url: prueba.url || null } };
     }
     if (tipo === 'json_path') {
-      // Un campo de un JSON, comparado por IGUALDAD ESTRICTA contra un valor esperado. Es lo que
-      // permite arbitrar trabajo de verdad ("tu endpoint debe responder {ok:true, version:3}")
-      // sin abrir la puerta a criterios que opinan. El camino es literal y sin comodines:
-      // `a.b.0.c`. Nada de expresiones — una consulta que hay que interpretar deja de ser
-      // determinista, y este verificador solo acepta lo que decide igual dos veces.
-      if (!/^https:\/\//.test(prueba.url || '')) return { pasa: false, prueba: tipo, razon: 'the URL to verify must be https', evidencia: { url: prueba.url } };
-      if (typeof prueba.path !== 'string' || !prueba.path.length) return { pasa: false, prueba: tipo, razon: 'json_path needs a path, for example "status" or "data.0.id"', evidencia: {} };
-      if (!('expect' in prueba)) return { pasa: false, prueba: tipo, razon: 'json_path needs an expect value to compare against', evidencia: {} };
-      const res = await fetchImpl(prueba.url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
-      if (!res.ok) return { pasa: false, prueba: tipo, razon: `${prueba.url} responded ${res.status}: nothing to read`, evidencia: { url: prueba.url, status: res.status } };
+      // Un campo de un JSON, comparado por IGUALDAD ESTRICTA contra un valor esperado, o su
+      // mera EXISTENCIA. Es lo que permite arbitrar trabajo de verdad ("tu endpoint debe
+      // responder {ok:true, version:3}") sin abrir la puerta a criterios que opinan. El camino
+      // es literal y sin comodines: `a.b.0.c` o `a.b[0].c`. Nada de expresiones — una consulta
+      // que hay que interpretar deja de ser determinista, y este verificador solo acepta lo que
+      // decide igual dos veces.
+      if (!esHttps(prueba.url)) return falla('the URL to verify must be https and public', { url: prueba.url });
+      const segmentos = segmentosDe(prueba.path);
+      if (!segmentos) return falla('json_path needs a path: literal, for example "status", "data.0.id" or "data[0].id"');
+      const conValor = 'expect' in prueba || 'equals' in prueba;
+      const conExiste = 'exists' in prueba;
+      if (conValor && conExiste) return falla('json_path takes either expect (or equals) or exists, not both');
+      if (!conValor && !conExiste) return falla('json_path needs an expect value to compare against, or exists: true|false');
+      if (conExiste && typeof prueba.exists !== 'boolean') return falla('json_path exists must be true or false');
+      const esperado = 'expect' in prueba ? prueba.expect : prueba.equals;
+      const res = await fetchImpl(prueba.url, { headers: { accept: 'application/json' }, redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+      const borde = delBorde(res); if (borde) return borde;
+      if (!res.ok) return falla(`${prueba.url} responded ${res.status}: nothing to read`, { url: prueba.url, status: res.status });
       let doc;
-      try { doc = JSON.parse(await res.text()); }
-      catch (e) { return { pasa: false, prueba: tipo, razon: `${prueba.url} did not return valid JSON`, evidencia: { url: prueba.url } }; }
+      try { doc = JSON.parse((await leerCuerpo(res, CUERPO_MAX)).texto); }
+      catch { return falla(`${prueba.url} did not return valid JSON`, { url: prueba.url }); }
       let visto = doc;
-      for (const seg of prueba.path.split('.')) {
+      for (const seg of segmentos) {
         if (visto == null || typeof visto !== 'object') { visto = undefined; break; }
         visto = Array.isArray(visto) ? visto[Number(seg)] : visto[seg];
       }
-      // La comparación es por forma canónica: {a:1,b:2} y {b:2,a:1} son el mismo valor.
-      const igual = canonical(visto ?? null) === canonical(prueba.expect ?? null);
       const corto = (v) => recorta(JSON.stringify(v ?? null), 120);
-      return { pasa: igual, prueba: tipo, razon: igual ? `${prueba.path} is ${corto(visto)}` : `${prueba.path} is ${corto(visto)}, expected ${corto(prueba.expect)}`, evidencia: { url: prueba.url, path: prueba.path, seen: visto ?? null, expect: prueba.expect ?? null } };
+      if (conExiste) {
+        const hay = visto !== undefined;
+        const pasa = hay === prueba.exists;
+        return { pasa, prueba: tipo, razon: `${prueba.path} ${hay ? 'exists' : 'does not exist'}${pasa ? '' : `, expected it ${prueba.exists ? 'to exist' : 'not to exist'}`}`, evidencia: { url: prueba.url, path: prueba.path, exists: hay, expect_exists: prueba.exists } };
+      }
+      // La comparación es por forma canónica: {a:1,b:2} y {b:2,a:1} son el mismo valor.
+      const igual = visto !== undefined && canonical(visto ?? null) === canonical(esperado ?? null);
+      return { pasa: igual, prueba: tipo, razon: igual ? `${prueba.path} is ${corto(visto)}` : `${prueba.path} is ${visto === undefined ? 'missing' : corto(visto)}, expected ${corto(esperado)}`, evidencia: { url: prueba.url, path: prueba.path, seen: visto ?? null, expect: esperado ?? null } };
+    }
+    if (tipo === 'regex') {
+      // Sobre el primer MB del cuerpo, con un patrón acotado (ver patronSeguro). Si el cuerpo
+      // era más largo, el veredicto lo dice: lo que se miró es lo que se descargó.
+      if (!esHttps(prueba.url)) return falla('the URL to verify must be https and public', { url: prueba.url });
+      const flags = prueba.flags ?? '';
+      const seguro = patronSeguro(prueba.pattern, flags);
+      if (!seguro.ok) return falla(seguro.razon, { pattern: recorta(String(prueba.pattern ?? ''), 80) });
+      const res = await fetchImpl(prueba.url, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+      const borde = delBorde(res); if (borde) return borde;
+      if (!res.ok) return falla(`${prueba.url} responded ${res.status}: nothing to read`, { url: prueba.url, status: res.status });
+      const { texto, bytes, truncado } = await leerCuerpo(res, REGEX_MAX);
+      // Línea por línea y cada línea recortada a 2 KB: con un solo cuantificador sin tope el peor
+      // caso es cuadrático sobre 2 KB, no sobre 1 MB. Un patrón no puede casar a través de líneas.
+      const re = new RegExp(prueba.pattern, flags.replace('s', ''));
+      const pasa = texto.split('\n').some((l) => re.test(l.length > REGEX_LINEA ? l.slice(0, REGEX_LINEA) : l));
+      const alcance = truncado ? ` (only the first ${REGEX_MAX} bytes were read)` : '';
+      return { pasa, prueba: tipo, razon: pasa ? `the body of ${prueba.url} matches /${prueba.pattern}/${flags}${alcance}` : `the body of ${prueba.url} does not match /${prueba.pattern}/${flags}${alcance}`, evidencia: { url: prueba.url, pattern: prueba.pattern, flags, bytes_read: bytes, truncated: truncado } };
+    }
+    if (tipo === 'size') {
+      if (!esHttps(prueba.url)) return falla('the URL to verify must be https and public', { url: prueba.url });
+      const max = prueba.max_bytes, min = prueba.min_bytes;
+      const entero = (v) => v === undefined || (Number.isInteger(v) && v >= 0);
+      if (!entero(max) || !entero(min) || (max === undefined && min === undefined)) return falla('size needs max_bytes and/or min_bytes as non-negative integers');
+      if (max !== undefined && min !== undefined && min > max) return falla('size: min_bytes cannot exceed max_bytes');
+      const res = await fetchImpl(prueba.url, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+      const borde = delBorde(res); if (borde) return borde;
+      if (!res.ok) return falla(`${prueba.url} responded ${res.status}: nothing to measure`, { url: prueba.url, status: res.status });
+      // Se cuenta lo que llega, no lo que dice content-length (que puede faltar o mentir). Se
+      // lee hasta un byte más que el tope más alto que importa: con eso ya se sabe de qué lado cae.
+      const tope = Math.max(CUERPO_MAX, max ?? 0, min ?? 0) + 1;
+      const { bytes, truncado } = await leerCuerpo(res, tope);
+      const visto = truncado ? `more than ${tope - 1}` : String(bytes);
+      const bajoMax = max === undefined || (!truncado && bytes <= max);
+      const sobreMin = min === undefined || bytes >= min;
+      const pasa = bajoMax && sobreMin;
+      const limites = [max !== undefined ? `at most ${max}` : null, min !== undefined ? `at least ${min}` : null].filter(Boolean).join(' and ');
+      return { pasa, prueba: tipo, razon: pasa ? `${prueba.url} is ${visto} bytes (${limites})` : `${prueba.url} is ${visto} bytes, expected ${limites}`, evidencia: { url: prueba.url, bytes: truncado ? null : bytes, more_than: truncado ? tope - 1 : null, max_bytes: max ?? null, min_bytes: min ?? null } };
+    }
+    if (tipo === 'header') {
+      if (!esHttps(prueba.url)) return falla('the URL to verify must be https and public', { url: prueba.url });
+      if (typeof prueba.name !== 'string' || !/^[A-Za-z0-9-]{1,80}$/.test(prueba.name)) return falla('header needs a name (letters, digits and dashes)');
+      if (typeof prueba.equals !== 'string') return falla('header needs equals: the exact value expected, as a string');
+      const res = await fetchImpl(prueba.url, { method: prueba.method || 'GET', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+      const borde = delBorde(res); if (borde) return borde;
+      const nombre = prueba.name.toLowerCase();
+      const visto = typeof res.headers?.get === 'function' ? res.headers.get(nombre) : (res.headers?.[nombre] ?? null);
+      const pasa = visto === prueba.equals;
+      return { pasa, prueba: tipo, razon: pasa ? `${prueba.url} sends ${nombre}: ${recorta(visto, 120)}` : (visto == null ? `${prueba.url} does not send the ${nombre} header, expected ${recorta(prueba.equals, 120)}` : `${prueba.url} sends ${nombre}: ${recorta(visto, 120)}, expected ${recorta(prueba.equals, 120)}`), evidencia: { url: prueba.url, name: nombre, seen: visto, equals: prueba.equals, status: res.status } };
     }
     // exit_0: solo en Node, sin shell interpretado (nada de `sh -c`), con timeout y sin heredar stdio.
     const { spawn } = await import('node:child_process');
     const argv = Array.isArray(prueba.argv) ? prueba.argv : null;
     if (!argv || !argv.length || typeof argv[0] !== 'string') {
-      return { pasa: false, prueba: tipo, razon: 'exit_0 necesita argv: ["comando","arg1",…]; no se acepta una línea de shell', evidencia: {} };
+      return falla('exit_0 necesita argv: ["comando","arg1",…]; no se acepta una línea de shell');
     }
     const res = await new Promise((resolve) => {
       const p = spawn(argv[0], argv.slice(1), { cwd: prueba.cwd || undefined, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'], shell: false, env: { PATH: process.env.PATH } });
@@ -148,6 +321,36 @@ export async function veredicto(pruebas, opts = {}) {
   return { pasa, indeciso, razon, resultados };
 }
 
+// NX-305 — La prueba de un contrato que nace de un PEDIDO al catálogo. La ficha publica el
+// `kind` y una descripción en prosa (`template`); los valores concretos (la URL, el hash, el
+// camino) los pone quien contrata, en el `input` del pedido. Sólo entran los campos que la
+// prueba lee: ni el comprador cuela uno ajeno ni el vendedor uno que la debilite.
+//
+// `exit_0` NO se deriva de un pedido a propósito: el `argv` lo escribiría el comprador y lo
+// correría la casa del vendedor, que cotiza sola. Un vendedor que auto-cotiza sería el proxy
+// de cualquiera para ejecutar comandos en la casa. Se cotiza a mano o no se cotiza.
+export const CAMPOS_PRUEBA = {
+  http_status: { requiere: ['url'], opcionales: ['expect', 'method'] },
+  sha256: { requiere: ['expect'], opcionales: ['url'] },
+  json_path: { requiere: ['url', 'path', 'expect'], opcionales: [] },
+};
+export function pruebaDeAceptacion(acceptance, input = {}) {
+  const kind = acceptance?.kind;
+  const campos = CAMPOS_PRUEBA[kind];
+  if (!campos) throw new Error(`acceptance.kind "${kind}" cannot be derived from a request; a request can only fill: ${Object.keys(CAMPOS_PRUEBA).join(', ')}`);
+  const dado = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const faltan = campos.requiere.filter((k) => dado[k] === undefined);
+  if (faltan.length) throw new Error(`the ${kind} test needs ${faltan.join(', ')} in the request input (${acceptance.template})`);
+  const verify = { type: kind };
+  for (const k of [...campos.requiere, ...campos.opcionales]) if (dado[k] !== undefined) verify[k] = dado[k];
+  // Lo que verifica@ va a rechazar al correr se rechaza AQUÍ, antes de firmar: una prueba que
+  // nunca puede pasar castigaría al vendedor por lo que escribió el comprador.
+  if (verify.url !== undefined && !/^https:\/\//.test(String(verify.url))) throw new Error(`the ${kind} test needs an https url; the request gave ${JSON.stringify(verify.url)}`);
+  if (kind === 'sha256' && !/^[0-9a-f]{64}$/.test(String(verify.expect).toLowerCase())) throw new Error('the sha256 test needs expect as 64 hex characters');
+  if (kind === 'json_path' && (typeof verify.path !== 'string' || !verify.path.length)) throw new Error('the json_path test needs path as a non-empty string');
+  return verify;
+}
+
 // Un contrato es verificable por la casa si declara pruebas en sus términos y nombra
 // como árbitro al verificador de la casa. Sin ambas cosas, nadie toca ese escrow.
 export function pruebasDe(contrato) {

package/src/nucleo/almacen-d1.js

@@ -8,6 +8,7 @@
 // el roundtrip y las firmas siguen verificando (invariante 7).
 
 import { LibroError } from '../libro/errores.js';
+import { filaDeIndice, codificarCursor, CADUCO } from '../correo/indice.js';
 
 const j = (v) => JSON.stringify(v);
 const p = (row, col = 'doc') => (row ? JSON.parse(row[col]) : null);
@@ -71,6 +72,16 @@ export class D1Store {
     const r = await this.db.prepare('UPDATE nyx5_mailbox SET acked = ? WHERE local = ? AND id = ? AND acked IS NULL').bind(iso(), local, id).run();
     return r.meta.changes === 1;
   }
+  // Historial: lo pendiente y lo confirmado, los últimos N en orden de llegada (índice 0006).
+  async listMailHistory(local, { limit = 200 } = {}) {
+    const r = await this.db.prepare('SELECT doc, acked FROM nyx5_mailbox WHERE local = ? ORDER BY received DESC, id DESC LIMIT ?').bind(local, limit).all();
+    return r.results.map((row) => ({ ...JSON.parse(row.doc), acked: row.acked || null })).reverse();
+  }
+  // Lo pendiente llegado después de un momento: la espera en tiempo real pregunta esto cada segundo,
+  // así que filtra en SQL en vez de traer el buzón entero.
+  async listMailSince(local, sinceIso) {
+    return (await this.db.prepare('SELECT doc FROM nyx5_mailbox WHERE local = ? AND acked IS NULL AND received > ? ORDER BY received, id').bind(local, sinceIso || '').all()).results.map((r) => JSON.parse(r.doc));
+  }
 
   // --- cola de salida ---
   _jobRow(job) { return [job.id, j(job), job.next_attempt, job.status, job.claimed_until || 0]; }
@@ -108,6 +119,49 @@ export class D1Store {
   }
   async pruneNonces(beforeMs) { await this.db.prepare('DELETE FROM nyx5_nonces WHERE ts < ?').bind(beforeMs).run(); }
 
+  // --- kv con vencimiento (0006): clientes OAuth, códigos de un uso, tokens (hash) y la bóveda ---
+  async kvGet(ns, key, nowMs = Date.now()) {
+    return p(await this.db.prepare('SELECT doc FROM nyx5_kv WHERE ns = ? AND key = ? AND (expires IS NULL OR expires > ?)').bind(ns, key, nowMs).first());
+  }
+  async kvPut(ns, key, doc, expires = null) {
+    await this.db.prepare('INSERT INTO nyx5_kv (ns, key, doc, expires, created) VALUES (?, ?, ?, ?, ?) ON CONFLICT(ns, key) DO UPDATE SET doc = excluded.doc, expires = excluded.expires')
+      .bind(ns, key, j(doc), expires, iso()).run();
+  }
+  async kvPutIfAbsent(ns, key, doc, expires = null, nowMs = Date.now()) {
+    await this.db.prepare('DELETE FROM nyx5_kv WHERE ns = ? AND key = ? AND expires IS NOT NULL AND expires <= ?').bind(ns, key, nowMs).run();
+    const r = await this.db.prepare('INSERT OR IGNORE INTO nyx5_kv (ns, key, doc, expires, created) VALUES (?, ?, ?, ?, ?)').bind(ns, key, j(doc), expires, iso()).run();
+    return r.meta.changes === 1;
+  }
+  // Tomar y borrar en UNA sentencia: dos canjes simultáneos del mismo código no pueden ganar los dos.
+  async kvTake(ns, key, nowMs = Date.now()) {
+    const r = await this.db.prepare('DELETE FROM nyx5_kv WHERE ns = ? AND key = ? RETURNING doc, expires').bind(ns, key).all();
+    const row = r.results[0];
+    if (!row || (row.expires != null && row.expires <= nowMs)) return null;
+    return JSON.parse(row.doc);
+  }
+  // Contador atómico con vencimiento en UNA sentencia: dos isolates que suman a la vez no pierden
+  // ninguna. Un contador ya vencido arranca de nuevo en 1 (la purga puede no haber pasado aún).
+  // `by`: cuánto suma (1 por defecto; los bytes de un cupo diario, por ejemplo).
+  async kvIncrement(ns, key, expires = null, nowMs = Date.now(), by = 1) {
+    const paso = String(Math.trunc(Number(by) || 0));
+    const r = await this.db.prepare(`INSERT INTO nyx5_kv (ns, key, doc, expires, created) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(ns, key) DO UPDATE SET
+        doc = CASE WHEN nyx5_kv.expires IS NOT NULL AND nyx5_kv.expires <= ? THEN ? ELSE CAST(CAST(nyx5_kv.doc AS INTEGER) + CAST(? AS INTEGER) AS TEXT) END,
+        expires = excluded.expires
+      RETURNING doc`).bind(ns, key, paso, expires, iso(), nowMs, paso, paso).all();
+    return Number(r.results[0].doc);
+  }
+  async kvDelete(ns, key) { await this.db.prepare('DELETE FROM nyx5_kv WHERE ns = ? AND key = ?').bind(ns, key).run(); }
+  // Las claves vivas de un espacio que empiezan por `prefix`, en orden de clave. `%` y `_` del
+  // prefijo se escapan: son comodines de LIKE y un prefijo no es un patrón.
+  // `after`: sólo claves estrictamente mayores (paginación por clave).
+  async kvList(ns, { prefix = '', limit = 1000, after } = {}, nowMs = Date.now()) {
+    const patron = `${String(prefix).replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+    const r = await this.db.prepare(`SELECT key, doc FROM nyx5_kv WHERE ns = ? AND key LIKE ? ESCAPE '\\' AND key > ? AND (expires IS NULL OR expires > ?) ORDER BY key LIMIT ?`).bind(ns, patron, after == null ? '' : String(after), nowMs, limit).all();
+    return r.results.map((row) => ({ key: row.key, doc: JSON.parse(row.doc) }));
+  }
+  async kvPurge(nowMs = Date.now()) { await this.db.prepare('DELETE FROM nyx5_kv WHERE expires IS NOT NULL AND expires <= ?').bind(nowMs).run(); }
+
   // --- pins (una fila por dominio: el primero gana y ningún isolate pisa lo que otro aprendió) ---
   async getPins() {
     const r = await this.db.prepare('SELECT domain, kid FROM nyx5_pin').all();
@@ -139,7 +193,16 @@ export class D1Store {
     return this.db.prepare('INSERT INTO nyx5_libro_contratos (id, quote_id, doc) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc, quote_id = excluded.quote_id').bind(c.id, c.quote_id || null, j(c));
   }
   async libroPutContract(c) { await this._contractStmt(c).run(); }
-  async libroListContracts() { return (await this.db.prepare('SELECT doc FROM nyx5_libro_contratos').all()).results.map((r) => JSON.parse(r.doc)); }
+  // Filtro por estado sobre json_extract(doc,'$.state'), cubierto por el índice de expresión de la
+  // migración 0009: el reloj de la casa lee sólo los contratos abiertos, no la tabla entera. Sin
+  // columna nueva: el estado ya vive en el doc y una columna sería una segunda verdad que mantener.
+  async libroListContracts({ state = null } = {}) {
+    if (state == null) return (await this.db.prepare('SELECT doc FROM nyx5_libro_contratos').all()).results.map((r) => JSON.parse(r.doc));
+    const estados = Array.isArray(state) ? state : [state];
+    if (!estados.length) return [];
+    const sql = `SELECT doc FROM nyx5_libro_contratos WHERE json_extract(doc, '$.state') IN (${estados.map(() => '?').join(', ')})`;
+    return (await this.db.prepare(sql).bind(...estados.map(String)).all()).results.map((r) => JSON.parse(r.doc));
+  }
   async libroFindContractByQuote(quoteId) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_contratos WHERE quote_id = ?').bind(quoteId).first()); }
   async libroGetMandate(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_mandatos WHERE id = ?').bind(id).first()); }
   _mandateStmt(m) { return this.db.prepare('INSERT INTO nyx5_libro_mandatos (id, doc) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc').bind(m.id, j(m)); }
@@ -147,6 +210,15 @@ export class D1Store {
   async libroListMandates() { return (await this.db.prepare('SELECT doc FROM nyx5_libro_mandatos').all()).results.map((r) => JSON.parse(r.doc)); }
   async libroGetOp(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_ops WHERE id = ?').bind(id).first()); }
   async libroPutOp(id, v) { await this.db.prepare('INSERT INTO nyx5_libro_ops (id, doc) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc').bind(id, j(v)).run(); }
+
+  // --- notaría (NX-601): sellos de hash (migrations/0008_notaria.sql) ---
+  async notariaGet(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_notaria WHERE id = ?').bind(id).first()); }
+  async notariaList(sha256) { return (await this.db.prepare('SELECT doc FROM nyx5_notaria WHERE sha256 = ? ORDER BY at, id').bind(sha256).all()).results.map((r) => JSON.parse(r.doc)); }
+  async notariaFind(sha256, by) { return p(await this.db.prepare('SELECT doc FROM nyx5_notaria WHERE sha256 = ? AND "by" = ?').bind(sha256, by).first()); }
+  // Sin ON CONFLICT a propósito: el índice único (sha256, by) es el candado, y un choque tiene
+  // que tirar el batch entero (421 reintentable), no pisar el sello anterior en silencio.
+  _selloStmt(s) { return this.db.prepare('INSERT INTO nyx5_notaria (id, sha256, "by", at, doc) VALUES (?, ?, ?, ?, ?)').bind(s.id, s.sha256, s.by, s.at, j(s)); }
+  async notariaPut(s) { try { await this._selloStmt(s).run(); } catch (e) { throw this._traducirConflicto(e); } }
   // ---------- instrumentación ----------
   async putEvent(e) { await this.db.prepare('INSERT OR IGNORE INTO nyx5_eventos (id, name, ts, actor, data) VALUES (?, ?, ?, ?, ?)').bind(e.id, e.name, e.ts, e.actor || null, j(e.data || {})).run(); }
   async listEvents({ name = null, since = null, limit = 500 } = {}) {
@@ -156,11 +228,28 @@ export class D1Store {
     const r = await this.db.prepare(`SELECT id, name, ts, actor, data FROM nyx5_eventos WHERE ${cond.join(' AND ')} ORDER BY ts DESC LIMIT ?`).bind(...bind, Number(limit)).all();
     return r.results.map((x) => ({ ...x, data: JSON.parse(x.data) })).reverse();
   }
-  async libroStatement(account, limit) {
-    const r = await this.db.prepare(`
-      SELECT doc FROM nyx5_libro_diario WHERE n IN (SELECT DISTINCT n FROM nyx5_libro_lineas WHERE account = ?)
-      ORDER BY n DESC LIMIT ?`).bind(account, limit).all();
-    return r.results.map((row) => JSON.parse(row.doc)).reverse();
+  // Extracto por cuenta en [since, until) sobre `at` del asiento (json_extract sobre el doc: la
+  // fecha ya vive ahí, sin migración). Los `limit` más recientes y el total del rango.
+  _statementWhere(account, since, until) {
+    const cond = ['n IN (SELECT DISTINCT n FROM nyx5_libro_lineas WHERE account = ?)']; const binds = [account];
+    if (since) { cond.push("json_extract(doc, '$.at') >= ?"); binds.push(since); }
+    if (until) { cond.push("json_extract(doc, '$.at') < ?"); binds.push(until); }
+    return { where: cond.join(' AND '), binds };
+  }
+  async libroStatementRange(account, { since = null, until = null, limit = 20 } = {}) {
+    const { where, binds } = this._statementWhere(account, since, until);
+    const total = Number((await this.db.prepare(`SELECT COUNT(*) AS c FROM nyx5_libro_diario WHERE ${where}`).bind(...binds).first())?.c || 0);
+    const r = await this.db.prepare(`SELECT doc FROM nyx5_libro_diario WHERE ${where} ORDER BY n DESC LIMIT ?`).bind(...binds, limit).all();
+    return { entries: r.results.map((row) => JSON.parse(row.doc)).reverse(), total };
+  }
+  async libroStatement(account, limit) { return (await this.libroStatementRange(account, { limit })).entries; }
+  // Saldo de una cuenta antes del asiento `n` y/o de la fecha `at`, sumado de las líneas.
+  async libroBalanceBefore(account, { n = null, at = null } = {}) {
+    const cond = ['l.account = ?']; const binds = [account];
+    if (n != null) { cond.push('l.n < ?'); binds.push(n); }
+    if (at != null) { cond.push("json_extract(d.doc, '$.at') < ?"); binds.push(at); }
+    const row = await this.db.prepare(`SELECT COALESCE(SUM(l.delta), 0) AS s FROM nyx5_libro_lineas l JOIN nyx5_libro_diario d ON d.n = l.n WHERE ${cond.join(' AND ')}`).bind(...binds).first();
+    return Number(row?.s || 0);
   }
 
   // Un movimiento del Libro, atómico. El orden importa: el diario va primero (PK n = candado
@@ -171,6 +260,7 @@ export class D1Store {
     if (bundle.state) stmts.push(this.db.prepare('UPDATE nyx5_libro_state SET seq = ?, balances = ? WHERE id = 1').bind(bundle.state.seq, j(bundle.state.balances)));
     for (const c of bundle.contracts || []) stmts.push(this._contractStmt(c));
     for (const m of bundle.mandates || []) stmts.push(this._mandateStmt(m));
+    for (const s of bundle.sellos || []) stmts.push(this._selloStmt(s));
     if (bundle.op) stmts.push(this.db.prepare('INSERT INTO nyx5_libro_ops (id, doc) VALUES (?, ?)').bind(bundle.op.id, j(bundle.op.result)));
     return stmts;
   }
@@ -212,21 +302,60 @@ export class D1Store {
   async indexGetHouse(domain) { return p(await this.db.prepare('SELECT doc FROM nyx5_indice_casas WHERE domain = ?').bind(domain).first()); }
   async indexPutHouse(h) { await this.db.prepare('INSERT INTO nyx5_indice_casas (domain, doc) VALUES (?, ?) ON CONFLICT(domain) DO UPDATE SET doc = excluded.doc').bind(h.domain, j(h)).run(); }
   async indexListHouses() { return (await this.db.prepare('SELECT doc FROM nyx5_indice_casas').all()).results.map((r) => JSON.parse(r.doc)); }
+  // Reemplazo por casa con generación: cada fila conserva un historial corto de sus puntajes
+  // (hist, first_gen) para que un recorrido por cursor no repita ni salte a quien cambió de
+  // puntaje entre página y página (cabecera de src/correo/indice.js).
   async indexReplaceAgents(domain, cards) {
+    const previas = (await this.db.prepare('SELECT address, first_gen, hist FROM nyx5_indice_agentes WHERE house = ?').bind(domain).all()).results;
+    const previo = new Map(previas.map((r) => [r.address, { first_gen: r.first_gen, hist: JSON.parse(r.hist || '[]') }]));
+    const gen = ((await this.db.prepare('SELECT COALESCE(MAX(gen), 0) AS g FROM nyx5_indice_agentes').first()).g || 0) + 1;
     await this.db.batch([
       this.db.prepare('DELETE FROM nyx5_indice_agentes WHERE house = ?').bind(domain),
-      ...cards.map((c) => this.db.prepare('INSERT INTO nyx5_indice_agentes (house, address, doc) VALUES (?, ?, ?)').bind(domain, c.address, j(c))),
+      ...cards.map((c) => {
+        const r = filaDeIndice(domain, c, gen, previo.get(c.address) || null);
+        return this.db.prepare('INSERT INTO nyx5_indice_agentes (house, address, doc, tags, langs, price_min, score, jobs_done, gen, first_gen, hist) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+          .bind(domain, c.address, j(c), j(r.tags), j(r.langs), r.price_min, r.score, r.jobs_done, r.gen, r.first_gen, j(r.hist));
+      }),
     ]);
   }
-  async indexSearch({ q, capability, accepts, house, limit = 50, offset = 0 } = {}) {
+  // La misma búsqueda que buscarEnMemoria (indice.js), en SQL. `g` va como literal entero (ya
+  // validado como entero seguro) porque la clave de orden aparece varias veces en la consulta.
+  async indexSearch(f = {}) {
+    const gActual = (await this.db.prepare('SELECT COALESCE(MAX(gen), 0) AS g FROM nyx5_indice_agentes').first()).g || 0;
+    if (f.cursor && f.cursor.g > gActual) throw Object.assign(new Error('invalid cursor: it names a generation of the index that does not exist'), { status: 400 });
+    const g = f.cursor ? f.cursor.g : gActual;
+    if (!Number.isSafeInteger(g) || g < 0) throw Object.assign(new Error('invalid cursor'), { status: 400 });
+    // El puntaje congelado en g: la última entrada del historial con generación <= g; NULL si la
+    // dirección entró al índice después de g (claveCongelada, en indice.js, es la referencia).
+    const ULT = `(SELECT json_extract(e.value, '$.s') FROM json_each(hist) e WHERE json_extract(e.value, '$.g') <= ${g} ORDER BY json_extract(e.value, '$.g') DESC LIMIT 1)`;
+    const K = `(CASE WHEN first_gen > ${g} THEN NULL ELSE ${ULT} END)`;
     const where = []; const binds = [];
-    if (house) { where.push('house = ?'); binds.push(house); }
-    if (capability) { where.push("json_extract(doc, '$.capabilities.' || ?) IS NOT NULL"); binds.push(capability); }
-    if (accepts) { where.push("EXISTS (SELECT 1 FROM json_each(doc, '$.capabilities.accepts') WHERE value = ?)"); binds.push(accepts); }
-    if (q) { where.push('lower(doc) LIKE ?'); binds.push(`%${String(q).toLowerCase()}%`); }
+    if (f.house) { where.push('house = ?'); binds.push(f.house); }
+    if (f.capability) { where.push("json_extract(doc, '$.capabilities.' || ?) IS NOT NULL"); binds.push(f.capability); }
+    if (f.accepts) { where.push("EXISTS (SELECT 1 FROM json_each(doc, '$.capabilities.accepts') WHERE value = ?)"); binds.push(f.accepts); }
+    if (f.tag) { where.push('EXISTS (SELECT 1 FROM json_each(tags) WHERE value = ?)'); binds.push(f.tag); }
+    if (f.lang) { where.push("EXISTS (SELECT 1 FROM json_each(langs) WHERE value = ? OR value LIKE ? || '-%')"); binds.push(f.lang, f.lang); }
+    if (f.price_max != null) { where.push('price_min IS NOT NULL AND price_min <= ?'); binds.push(f.price_max); }
+    if (f.q) { where.push("lower(doc) LIKE ? ESCAPE '\\'"); binds.push(`%${String(f.q).toLowerCase().replace(/[\\%_]/g, (c) => '\\' + c)}%`); }
+    const wBase = where.length ? `WHERE ${where.join(' AND ')}` : '';
+    if (f.cursor) {
+      // Caduco: una fila que ya existía en g y cuyo historial no conserva ninguna entrada <= g.
+      const caduco = (await this.db.prepare(`SELECT COUNT(*) AS c FROM nyx5_indice_agentes ${wBase} ${where.length ? 'AND' : 'WHERE'} first_gen <= ${g} AND NOT EXISTS (SELECT 1 FROM json_each(hist) e WHERE json_extract(e.value, '$.g') <= ${g})`).bind(...binds).first()).c;
+      if (caduco > 0) throw Object.assign(new Error(CADUCO), { status: 410 });
+    }
+    if (f.min_score != null) { where.push(`${K} >= ?`); binds.push(f.min_score); }
     const w = where.length ? `WHERE ${where.join(' AND ')}` : '';
     const total = (await this.db.prepare(`SELECT COUNT(*) AS c FROM nyx5_indice_agentes ${w}`).bind(...binds).first()).c;
-    const rows = await this.db.prepare(`SELECT doc FROM nyx5_indice_agentes ${w} ORDER BY house, address LIMIT ? OFFSET ?`).bind(...binds, limit, offset).all();
-    return { total, offset, agents: rows.results.map((r) => JSON.parse(r.doc)) };
+    const keyset = []; const kb = [];
+    if (f.cursor) {
+      if (f.cursor.s == null) { keyset.push(`${K} IS NULL AND address > ?`); kb.push(f.cursor.a); }
+      else { keyset.push(`(${K} < ? OR (${K} = ? AND address > ?) OR ${K} IS NULL)`); kb.push(f.cursor.s, f.cursor.s, f.cursor.a); }
+    }
+    const wPag = [...where, ...keyset].length ? `WHERE ${[...where, ...keyset].join(' AND ')}` : '';
+    const rows = (await this.db.prepare(`SELECT address, ${K} AS k, doc FROM nyx5_indice_agentes ${wPag} ORDER BY k DESC NULLS LAST, address ASC LIMIT ?`).bind(...binds, ...kb, f.limit + 1).all()).results;
+    const pagina = rows.slice(0, f.limit);
+    const ultima = pagina[pagina.length - 1];
+    const next_cursor = rows.length > f.limit ? codificarCursor({ s: ultima.k ?? null, a: ultima.address, g }) : null;
+    return { total, agents: pagina.map((r) => JSON.parse(r.doc)), next_cursor };
   }
 }