@nyx5/nyx5 0.6.0 → 0.7.0

package/src/libro/libro.js

@@ -28,6 +28,7 @@
 import { signObject, verifyObject, canonical, sha256hex, uuid } from '../nucleo/crypto.js';
 import { Resolver, parseAddress } from '../correo/resolver.js';
 import { CONTRATOS } from './contratos.js';
+import { boletaDe } from './estado.js';
 import { LibroError } from './errores.js';
 export { LibroError };
 
@@ -42,10 +43,13 @@ const iso = () => new Date().toISOString();
 export class Libro {
   // feeBps: fee de la casa en basis points enteros (1000 = 10%). `feePct` sigue aceptándose
   // como azúcar (0.10 -> 1000) pero el cálculo es siempre entero: sin punto flotante en el dinero.
-  constructor({ domain, store, keys, resolver, feeBps = null, feePct = null, welcome = 0, log = () => {} }) {
+  // reclaimGraceMs / reviewWindowMs (NX-503): cuánto después del plazo el comprador recupera un
+  // escrow sin entrega, y cuánto tiene para objetar una entrega antes de que se libere sola.
+  constructor({ domain, store, keys, resolver, feeBps = null, feePct = null, welcome = 0, reclaimGraceMs = 24 * 3600_000, reviewWindowMs = 72 * 3600_000, log = () => {} }) {
     this.domain = domain; this.store = store; this.keys = keys; this.resolver = resolver;
     this.feeBps = feeBps ?? (feePct != null ? Math.round(feePct * 10_000) : 1000);
     this.welcome = welcome; this.log = log;
+    this.reclaimGraceMs = reclaimGraceMs; this.reviewWindowMs = reviewWindowMs;
     this.casa = `casa@${domain}`;
     this.address = `libro@${domain}`;
     this.tx = null; // transacción en curso: { state, asientos, contracts: Map, mandates: Map, op }
@@ -62,11 +66,11 @@ export class Libro {
   // y ambos entrarían, superando el tope.
   async _begin(concepto = 'control', refs = {}) {
     const base = await this.store.libroState();
-    this.tx = { base, state: null, asientos: [], contracts: new Map(), mandates: new Map(), op: null, concepto, refs };
+    this.tx = { base, state: null, asientos: [], contracts: new Map(), mandates: new Map(), sellos: [], op: null, concepto, refs };
   }
   _bundle() {
     const t = this.tx;
-    return { state: t.state, base: t.base, asientos: t.asientos, contracts: [...t.contracts.values()], mandates: [...t.mandates.values()], op: t.op };
+    return { state: t.state, base: t.base, asientos: t.asientos, contracts: [...t.contracts.values()], mandates: [...t.mandates.values()], sellos: t.sellos, op: t.op };
   }
   async _commit() {
     const t = this.tx;
@@ -90,6 +94,9 @@ export class Libro {
   putContract(c) { if (!this.tx) throw new LibroError(500, 'putContract fuera de transacción'); this.tx.contracts.set(c.id, c); }
   async getMandate(id) { return this.tx?.mandates.get(id) ?? await this.store.libroGetMandate(id); }
   putMandate(m) { if (!this.tx) throw new LibroError(500, 'putMandate fuera de transacción'); this.tx.mandates.set(m.id, m); }
+  // Sello de notaría (NX-601): no mueve dinero ni consume número de asiento. Su candado contra el
+  // doble sello es el índice único (sha256, by) del almacén, que hace fallar cerrado el commit.
+  putSello(s) { if (!this.tx) throw new LibroError(500, 'putSello fuera de transacción'); this.tx.sellos.push(s); }
 
   // ---------- consultas ----------
   get ops() { return Object.keys(CONTRATOS.ops); }
@@ -120,7 +127,9 @@ export class Libro {
     const cuenta = () => ({ n: 0, tokens: 0 });
     const h = {
       address, house: this.domain,
-      vendiendo: { entregas_aceptadas: cuenta(), entregas_devueltas: cuenta(), ventas_directas: cuenta() },
+      // entregas_por_silencio: liberadas por el reloj de la casa al vencer la ventana de revisión
+      // (NX-503). Silencio no es aceptación: se cuentan aparte, y también dentro de aceptadas.
+      vendiendo: { entregas_aceptadas: cuenta(), entregas_por_silencio: cuenta(), entregas_devueltas: cuenta(), ventas_directas: cuenta() },
       comprando: { encargos_liberados: cuenta(), encargos_devueltos: cuenta(), compras_directas: cuenta() },
       afirmando: { fianzas_sostenidas: cuenta(), fianzas_ejecutadas: cuenta(), fianzas_vigentes: cuenta() },
       avalando: { avales_sostenidos: cuenta(), avales_ejecutados: cuenta() },
@@ -142,7 +151,10 @@ export class Libro {
         else sumar(sostenida ? grupo.fianzas_sostenidas : grupo.fianzas_ejecutadas, monto);
       } else if (c.seller === address) {
         if (c.kind === 'spot') sumar(h.vendiendo.ventas_directas, monto);
-        else sumar(c.state === 'released' ? h.vendiendo.entregas_aceptadas : h.vendiendo.entregas_devueltas, monto);
+        else {
+          sumar(c.state === 'released' ? h.vendiendo.entregas_aceptadas : h.vendiendo.entregas_devueltas, monto);
+          if (c.state === 'released' && c.history?.some((x) => x.op === 'expire')) sumar(h.vendiendo.entregas_por_silencio, monto);
+        }
       } else {
         if (c.kind === 'spot') sumar(h.comprando.compras_directas, monto);
         else sumar(c.state === 'released' ? h.comprando.encargos_liberados : h.comprando.encargos_devueltos, monto);
@@ -150,6 +162,24 @@ export class Libro {
     }
     // Fianzas todavía en pie: no son historial cumplido, pero sí tokens en juego ahora mismo.
     for (const c of mios) if (c.kind === 'bond' && c.state === 'posted' && c.seller === address) sumar(h.afirmando.fianzas_vigentes, Number(c.amount) || 0);
+    // Arbitrados por la casa (NX-302): sólo los contratos en que este agente VENDÍA, el árbitro
+    // era `verifica@<casa>` y el veredicto terminal (release / refund / forfeit) lo dio ese
+    // árbitro, no una parte. Es la porción del historial que dos cómplices no pueden fabricar
+    // entre sí: para sumar aquí hay que pasar una prueba determinista que corre la casa. Un
+    // escrow liberado por el comprador, o por silencio (`expire`), queda fuera aunque el
+    // contrato nombrara a verifica@ de árbitro. Campo ADITIVO: la forma anterior no cambia.
+    const arbitro = `verifica@${this.domain}`;
+    h.arbitrados = { arbitro, liberados: cuenta(), devueltos: cuenta(), ejecutadas: cuenta() };
+    for (const c of mios) {
+      if (c.seller !== address || c.arbiter !== arbitro) continue;
+      if (!(Libro.TERMINALES[c.kind] || []).includes(c.state)) continue;
+      const veredicto = (c.history || []).filter((x) => ['release', 'refund', 'forfeit'].includes(x.op)).at(-1);
+      if (!veredicto || veredicto.by !== arbitro) continue;
+      const monto = Number(c.amount) || 0;
+      if (veredicto.op === 'release') sumar(h.arbitrados.liberados, monto);
+      else if (veredicto.op === 'refund') sumar(h.arbitrados.devueltos, monto);
+      else sumar(h.arbitrados.ejecutadas, monto);
+    }
     // El resumen es lo que un agente lee para decidir en una línea; el detalle queda arriba.
     const entregadas = h.vendiendo.entregas_aceptadas.n + h.vendiendo.ventas_directas.n;
     const falladas = h.vendiendo.entregas_devueltas.n;
@@ -162,6 +192,8 @@ export class Libro {
       // Sin historial no hay tasa: cero de cero no es 100%, es "todavía nada". Lo decimos así.
       cumplimiento: entregadas + falladas > 0 ? Number((entregadas / (entregadas + falladas)).toFixed(4)) : null,
       veracidad: afirmaciones > 0 ? Number((h.afirmando.fianzas_sostenidas.n / afirmaciones).toFixed(4)) : null,
+      // Lo que el índice federado usa para ordenar (§13): ponderado por tokens, null sin historial arbitrado.
+      puntaje_arbitrado: puntajeArbitrado(h.arbitrados),
     };
     return h;
   }
@@ -177,7 +209,7 @@ export class Libro {
     const next = { ...state.balances };
     for (const l of lines) {
       next[l.account] = (next[l.account] || 0) + l.delta;
-      if (next[l.account] < 0 && l.account !== this.casa) throw new LibroError(402, `saldo insuficiente en ${l.account} (tiene ${state.balances[l.account] || 0}, necesita ${-l.delta})`);
+      if (next[l.account] < 0 && l.account !== this.casa) throw new LibroError(402, `insufficient balance in ${l.account} (has ${state.balances[l.account] || 0}, needs ${-l.delta})`);
     }
     const asiento = signObject({ id: uuid(), n: state.seq + 1, at: iso(), house: this.domain, concept, lines, meta, refs }, this.keys);
     if (this.tx) {
@@ -228,8 +260,11 @@ export class Libro {
 
   // ---------- cotizaciones: documentos firmados por el vendedor ----------
   // Una cotización viaja adentro de un sobre (cifrado si se quiere) y se presenta al Libro al aceptar.
-  static buildQuote({ seller, buyer, house, contract = 'spot', price, concept, terms = {}, expires, arbiter = null, referrer = null }, sellerKeys) {
+  static buildQuote({ seller, buyer, house, contract = 'spot', price, concept, terms = {}, expires, arbiter = null, referrer = null, service = null }, sellerKeys) {
     if (!CONTRATOS[contract]?.quoteable) throw new LibroError(400, `contrato no cotizable: ${contract}`);
+    // `service` (NX-301): el id de un servicio publicado en la ficha del vendedor. Va firmado en la
+    // cotización y verifyQuote lo cruza con la ficha al aceptar: precio y contrato tienen que ser los publicados.
+    if (service != null && (typeof service !== 'string' || !/^[a-z0-9-]{1,40}$/.test(service))) throw new LibroError(400, 'service debe ser el id de un servicio de la ficha (letras minúsculas, dígitos y guiones)');
     if (arbiter) parseAddress(arbiter);
     // Comisión de referido: el vendedor firma en su cotización que le paga `share` (en basis points)
     // a quien trajo el trato. La comisión sale de LO QUE RECIBE el vendedor, no se suma al precio:
@@ -238,7 +273,7 @@ export class Libro {
       parseAddress(referrer.address);
       if (!Number.isInteger(referrer.share) || referrer.share <= 0) throw new LibroError(400, 'referrer.share debe ser un entero de basis points > 0');
     }
-    return signObject({ tipo: 'cotizacion', id: uuid(), house, seller, buyer, contract, price, currency: 'tok', concept, terms, arbiter, referrer: referrer || undefined, issued: iso(), expires: expires || null }, sellerKeys);
+    return signObject({ tipo: 'cotizacion', id: uuid(), house, seller, buyer, contract, price, currency: 'tok', concept, terms, arbiter, referrer: referrer || undefined, service: service || undefined, issued: iso(), expires: expires || null }, sellerKeys);
   }
   async verifyQuote(q, buyer) {
     if (q?.tipo !== 'cotizacion' || !q.id || !q.seller || !q.signature) throw new LibroError(400, 'cotización malformada');
@@ -260,6 +295,19 @@ export class Libro {
     let card;
     try { card = await this.resolver.agentCardForKid(q.seller, q.signature.kid); } catch (e) { throw new LibroError(e.permanent ? 403 : 421, `no se pudo verificar al vendedor: ${e.message}`); }
     if (!Resolver.acceptedKids(card).includes(q.signature.kid) || !verifyObject(q, q.signature.kid)) throw new LibroError(403, 'firma de la cotización inválida');
+    // Una dirección de sólo mensajes (la del Claude de un teléfono, cuya llave guarda la casa) no
+    // vende: aceptarle una cotización le movería saldo, que es justo lo que su dueño no autorizó.
+    if (card.delegation?.scope?.messages_only) throw new LibroError(403, 'the seller is a messages-only address: it cannot sell');
+    // Cotización sobre un servicio publicado (NX-301): se compara contra la ficha CERTIFICADA del
+    // vendedor tal como está hoy, nunca contra lo que la cotización dice de sí misma. Mismo espíritu
+    // que tareas.coincide: un precio o un contrato distintos del publicado son rechazo, no negociación.
+    // Si el vendedor cambió su catálogo después de cotizar, la cotización vieja ya no coincide y se rechaza.
+    if (q.service != null) {
+      if (typeof q.service !== 'string') throw new LibroError(400, 'service must be the id of a published service');
+      const s = (card.profile?.services || []).find((x) => x.id === q.service);
+      if (!s) throw new LibroError(400, `service "${q.service}" is not published in the profile of ${q.seller}`);
+      if (s.price.tokens !== q.price || s.contract !== q.contract) throw new LibroError(400, `service ${s.id} is published at ${s.price.tokens} tok as ${s.contract}; the quote says ${q.price} as ${q.contract}`);
+    }
     if (await this.store.libroFindContractByQuote(q.id)) throw new LibroError(409, 'cotización ya aceptada');
     return card;
   }
@@ -273,6 +321,9 @@ export class Libro {
     const body = env.content.body || {};
     const op = CONTRATOS.ops[body.op];
     if (!op) return { ok: false, code: 400, reason: `unknown operation: ${body.op}. Valid ones: ${Object.keys(CONTRATOS.ops).join(', ')}` };
+    // Sólo mensajes no opera el Libro, entre el sobre por donde entre: la regla vive donde se mueve
+    // el dinero, no sólo en la puerta (revisión del 11-sep-2026).
+    if (senderCard?.delegation?.scope?.messages_only) return { ok: false, code: 403, reason: 'this is a messages-only address: it cannot operate the ledger' };
     const ctx = { libro: this, env, from: env.from, body, senderCard, opHash: sha256hex(canonical(env)), scope: senderCard?.delegation?.scope || null };
     return this._serial(async () => {
       await this._begin(`op ${body.op}`, { op: env.id, op_sha256: ctx.opHash });
@@ -283,7 +334,11 @@ export class Libro {
         if (e instanceof LibroError) return { ok: false, code: e.code, reason: e.message };
         throw e;
       }
-      const out = { ok: true, code: 202, result: result.result, recibos: (result.recibos || []).map((r) => ({ ...r, body: { ...r.body, of: env.id, op: body.op, op_sha256: ctx.opHash, from: env.from } })), avisos: result.avisos || [] };
+      // Boleta (NX-501): todo recibo que lleva un asiento con reparto dice cuánto fue fee de la casa
+      // y cuánto comisión de referido, leído de las líneas del asiento (estado.js), en el único
+      // punto donde se arman los recibos.
+      const boleta = (b) => boletaDe(b.asiento, { casa: this.casa, feeBps: this.feeBps, share: b.contract?.referrer?.share ?? null });
+      const out = { ok: true, code: 202, result: result.result, recibos: (result.recibos || []).map((r) => ({ ...r, body: { ...r.body, ...boleta(r.body), of: env.id, op: body.op, op_sha256: ctx.opHash, from: env.from } })), avisos: result.avisos || [] };
       this.tx.op = { id: env.id, result: out };
       try { await this._commit(); }
       catch (e) {
@@ -301,7 +356,7 @@ export class Libro {
   // dedupe del sobre (inboundCommit) — así una reentrega jamás cobra la estampilla dos veces.
   async stamp(env, recipient, price) {
     const s = env.stamp;
-    if (!s || s.house !== this.domain || !Number.isInteger(s.amount) || s.amount < price) throw new LibroError(402, `este buzón exige estampilla de ${price} tok en la casa ${this.domain} (campo stamp: {house, amount})`);
+    if (!s || s.house !== this.domain || !Number.isInteger(s.amount) || s.amount < price) throw new LibroError(402, `this mailbox requires a stamp of ${price} tok in house ${this.domain} (stamp field: {house, amount})`);
     return this._serial(async () => {
     await this._begin('estampilla', { envelope: env.id });
     try {
@@ -313,3 +368,15 @@ export class Libro {
     });
   }
 }
+
+// Puntaje de reputación arbitrada: tokens liberados sobre tokens decididos por verifica@
+// (liberados + devueltos + fianzas ejecutadas). Ponderado por monto, no por cuenta: una entrega
+// de 5.000 pesa más que diez de 10. `null` cuando no hay nada decidido: cero de cero no es 100 %.
+// UNA definición: la usan `historial` (resumen.puntaje_arbitrado) y el índice federado.
+export function puntajeArbitrado(arbitrados) {
+  if (!arbitrados || typeof arbitrados !== 'object') return null;
+  const t = (k) => Number(arbitrados[k]?.tokens) || 0;
+  const total = t('liberados') + t('devueltos') + t('ejecutadas');
+  if (total <= 0) return null;
+  return Number((t('liberados') / total).toFixed(4));
+}

package/src/libro/notaria.js

@@ -0,0 +1,74 @@
+// Nyx5/1 — Notaría (NX-601): la casa sella el hash de un documento con fecha y firma.
+//
+// Qué certifica un sello: que en el instante `at` la casa recibió un sobre firmado (hash
+// `op_sha256`) en el que `by` declaró el hash `sha256`. Nada más. La casa no ve el documento, no
+// afirma que exista ni qué contiene: quien lo tenga puede demostrar que ya existía a esa fecha
+// presentando el documento (su hash coincide) y el sello (la firma de la casa verifica con la
+// tarjeta del dominio, sin cuenta).
+//
+// No mueve dinero: no hay asiento. El candado contra el doble sello es el índice único
+// (sha256, by) del almacén, no el número de asiento: dos sobres distintos del mismo agente con el
+// mismo hash producen UN sello (el primero) y la segunda petición recibe ese mismo sello. Dos
+// agentes distintos sí producen dos sellos: cada uno atestigua que ÉL lo declaró.
+//
+// Dos versiones firmadas del mismo sello, con el mismo id: `sello` (con `by`) y `anonimo` (con
+// `by: null`). La pública sirve la primera si el agente es visible y la segunda si es secreto,
+// para que un secreto no quede confirmado por su propio sello (NX-202) y aun así la firma
+// verifique. Las dos comparten id, sha256, at y op_sha256: son el mismo hecho, con o sin nombre.
+//
+// Qué NO cubre: no prueba autoría del documento (prueba quién lo DECLARÓ), no prueba que el
+// documento sea anterior a `at` (sólo que no es posterior), y no verifica que `media` o `name`
+// describan al documento: son lo que el declarante dijo.
+
+import { signObject, uuid } from '../nucleo/crypto.js';
+import { limpio } from '../correo/politica.js';
+import { LibroError } from './errores.js';
+
+export const SHA256_HEX = /^[0-9a-fA-F]{64}$/;
+export const LIMITES = Object.freeze({ name: 120, media: 100, note: 500 });
+
+const fail = (code, msg) => { throw new LibroError(code, msg); };
+
+// Valida el cuerpo de la op. Campos desconocidos se ignoran (invariante 7). El hash se normaliza
+// a minúsculas: el mismo documento no puede tener dos sellos por cómo se escribió su hash.
+export function validarNotarize(body = {}) {
+  if (typeof body.sha256 !== 'string' || !SHA256_HEX.test(body.sha256)) fail(400, 'sha256 must be the hex digest of the document: 64 hexadecimal characters');
+  const texto = (k) => {
+    if (body[k] == null) return null;
+    if (typeof body[k] !== 'string') fail(400, `${k} must be a string`);
+    return limpio(body[k], LIMITES[k]) || null;
+  };
+  return { sha256: body.sha256.toLowerCase(), name: texto('name'), media: texto('media'), note: texto('note') };
+}
+
+// Construye el registro firmado. `keys` son las llaves del dominio (las mismas que firman recibos).
+export function sellar({ sha256, name, media, note, by, house, at, op_sha256, secret = false }, keys) {
+  const cuerpo = { nyx5: '1', tipo: 'sello', id: uuid(), sha256, name, media, note, by, house, at, op_sha256 };
+  return {
+    id: cuerpo.id, sha256, by, at,
+    // `secret` es la visibilidad del declarante cuando selló: un agente de OTRA casa no se puede
+    // re-consultar en vivo desde aquí, así que lo que se supo al sellar es lo que manda para él.
+    secret: !!secret,
+    sello: signObject(cuerpo, keys),
+    anonimo: signObject({ ...cuerpo, by: null }, keys),
+  };
+}
+
+// Lo que se sirve al público por un registro: la versión con nombre si el declarante es
+// visible para «nadie» (quien pregunta sin cuenta), la anónima si no.
+export function selloPublico(doc, visible) { return visible ? doc.sello : doc.anonimo; }
+
+// La op del Libro. Corre dentro de la transacción de Libro.handle(): escribe con libro.putSello.
+export async function notarize(ctx) {
+  const { libro, from, body, senderCard, opHash } = ctx;
+  const v = validarNotarize(body);
+  const previo = await libro.store.notariaFind(v.sha256, from);
+  if (previo) {
+    // El mismo declarante ya selló este hash: se le devuelve ESE sello, no se crea otro. La
+    // receta lleva el hash del sobre que la pidió (invariante 5) aunque el sello sea anterior.
+    return { result: { seal: previo.sello, existing: true }, recibos: [{ to: [from], body: { seal: previo.sello, existing: true } }] };
+  }
+  const doc = sellar({ ...v, by: from, house: libro.domain, at: new Date().toISOString(), op_sha256: opHash, secret: senderCard?.visibility === 'secret' }, libro.keys);
+  libro.putSello(doc);
+  return { result: { seal: doc.sello, existing: false }, recibos: [{ to: [from], body: { seal: doc.sello, existing: false } }] };
+}

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,39 @@ 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).
+  async kvIncrement(ns, key, expires = null, nowMs = Date.now()) {
+    const r = await this.db.prepare(`INSERT INTO nyx5_kv (ns, key, doc, expires, created) VALUES (?, ?, '1', ?, ?)
+      ON CONFLICT(ns, key) DO UPDATE SET
+        doc = CASE WHEN nyx5_kv.expires IS NOT NULL AND nyx5_kv.expires <= ? THEN '1' ELSE CAST(CAST(nyx5_kv.doc AS INTEGER) + 1 AS TEXT) END,
+        expires = excluded.expires
+      RETURNING doc`).bind(ns, key, expires, iso(), nowMs).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(); }
+  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();
@@ -147,6 +191,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 +209,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 +241,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 +283,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 };
   }
 }