@nyx5/nyx5 0.6.0 → 0.8.0

package/src/libro/estado.js

@@ -0,0 +1,150 @@
+// Nyx5/1 — Boleta del asiento y estado de cuenta (NX-501).
+//
+// Dos lecturas del mismo diario, sin tocar el kernel:
+//   boletaDe(asiento)    -> qué parte del movimiento fue fee de la casa y qué parte comisión de
+//                           referido, LEÍDO de las líneas del asiento. No se recalcula: si el
+//                           asiento y una tasa discreparan, gana la línea, que es lo que movió.
+//   estadoDeCuenta(...)  -> el extracto de una cuenta en un rango de fechas: saldo inicial,
+//                           movimientos, saldo final y totales que cuadran. JSON o CSV (RFC 4180).
+//
+// Modelo de las filas: el fee y la comisión son filas PROPIAS, atribuidas a quien recibe el monto
+// bruto. El fee sale de lo que recibe el vendedor (el comprador paga el precio, ni más ni menos).
+// Para el vendedor de un spot de 200 con fee 10 % y comisión 15 %:
+//   in 200 (bruto, contraparte el comprador) · out 20 fee 20 (casa@) · out 30 (referidor)
+// y siempre opening + Σin − Σout = closing. `fee` es un subconjunto de `out`: marca qué salida
+// fue para la casa. Las filas de un mismo asiento comparten `entry`; el saldo tras la última
+// fila del asiento es el del Libro (los intermedios son de presentación).
+//
+// Qué NO cubre, dicho antes de que alguien lo suponga:
+//   - Movimientos donde la cuenta no aparece en una línea. Una fianza ejecutada mueve
+//     escrow → beneficiario: el afianzado salió del diario al depositarla.
+//   - El fee de una estampilla no pasa por un recibo del Libro (viaja en la respuesta x402 como
+//     `transaction`); sí aparece en el estado de cuenta del que la cobró.
+//   - Si la cuenta es a la vez referidor y pagador (net negativo), no se desglosa: una sola fila.
+
+import { LibroError } from './errores.js';
+
+export const CSV_CABECERA = Object.freeze(['date', 'entry', 'concept', 'counterparty', 'in', 'out', 'fee', 'balance']);
+
+// Fee y comisión de un asiento, leídos de sus líneas. `feeBps` (tasa de la casa) y `share` (bps
+// del referido) son contexto para que la boleta diga la tasa; el MONTO es siempre el de la línea.
+// `meta.fee > 0` distingue un fee de otra entrada positiva de la casa (una fianza ejecutada a su
+// favor no es fee). Nunca lanza: corre dentro de Libro.handle después de que la op ya decidió.
+export function boletaDe(asiento, { casa, feeBps = null, share = null } = {}) {
+  if (!asiento || !Array.isArray(asiento.lines)) return {};
+  const meta = asiento.meta || {};
+  const out = {};
+  const fee = meta.fee > 0 ? asiento.lines.find((l) => l.account === casa && l.delta > 0) : null;
+  if (fee) out.fee = { account: casa, amount: fee.delta, ...(feeBps != null ? { bps: feeBps } : {}) };
+  const com = meta.commission > 0 && meta.referrer ? asiento.lines.find((l) => l.account === meta.referrer && l.delta > 0) : null;
+  if (com) out.commission = { account: meta.referrer, amount: com.delta, ...(share != null ? { bps: share } : {}) };
+  return out;
+}
+
+// Las filas de UNA cuenta en UN asiento. [] si la cuenta no aparece en ninguna línea.
+export function filasDe(asiento, account, casa) {
+  const mias = asiento.lines.filter((l) => l.account === account);
+  if (!mias.length) return [];
+  const propio = mias.reduce((s, l) => s + l.delta, 0);
+  const meta = asiento.meta || {};
+  const { fee, commission } = boletaDe(asiento, { casa });
+  // Contraparte: las líneas del signo contrario que no son el fee ni la comisión (salvo que la
+  // cuenta sea justamente la casa o el referidor: entonces esas líneas son las suyas).
+  const excluidas = new Set([account, ...(fee ? [casa] : []), ...(commission ? [meta.referrer] : [])]);
+  const contra = asiento.lines.filter((l) => !excluidas.has(l.account) && Math.sign(l.delta) === -Math.sign(propio)).map((l) => l.account);
+  const base = { date: asiento.at, entry: asiento.id, n: asiento.n, concept: asiento.concept, counterparty: contra.join(';') };
+  // Quien recibe el bruto: net positivo, no es la casa ni el referidor, y el asiento repartió.
+  const bruto = propio > 0 && account !== casa && account !== meta.referrer && (fee || commission);
+  if (!bruto) return [{ ...base, kind: 'movement', in: propio > 0 ? propio : 0, out: propio < 0 ? -propio : 0, fee: 0 }];
+  const filas = [{ ...base, kind: 'movement', in: propio + (fee?.amount || 0) + (commission?.amount || 0), out: 0, fee: 0 }];
+  if (fee) filas.push({ ...base, kind: 'fee', concept: 'house fee', counterparty: casa, in: 0, out: fee.amount, fee: fee.amount });
+  if (commission) filas.push({ ...base, kind: 'commission', concept: 'referral commission', counterparty: meta.referrer, in: 0, out: commission.amount, fee: 0 });
+  return filas;
+}
+
+// Fecha ISO normalizada al formato exacto de `asiento.at` (toISOString), para que la comparación
+// lexicográfica en el almacén sea la misma que la numérica. Una fecha sola ("2026-09-13") es la
+// medianoche UTC de ese día: como `until` es exclusivo, `hasta=2026-09-14` cubre el 13 entero.
+function fechaIso(v, nombre) {
+  if (v == null || v === '') return null;
+  // Sin zona horaria, Node la interpreta en la del proceso y workerd en UTC: se exige Z u offset
+  // (una fecha sola, sin hora, es UTC en las dos).
+  const t = typeof v === 'string' && (/^\d{4}-\d{2}-\d{2}$/.test(v) || /(Z|[+-]\d{2}:?\d{2})$/.test(v)) ? Date.parse(v) : NaN;
+  if (Number.isNaN(t)) throw new LibroError(400, `${nombre} must be an ISO-8601 date, got ${JSON.stringify(v)}`);
+  return new Date(t).toISOString();
+}
+
+// El estado de cuenta de `account` en [since, until). `limit` acota cuántos asientos se listan
+// (se conservan los MÁS RECIENTES, como el statement de siempre); `max` es el techo que pone el
+// llamador (200 por correo, 1000 por HTTP). Sin rango, el límite por defecto sigue siendo 20.
+//
+// opening_balance es el saldo justo antes del primer asiento listado (sumado de sus líneas, no
+// leído de saldos), así que cuadra también cuando la lista está truncada. `ledger_balance` es lo
+// que dice el estado de saldos hoy: cuando el extracto llega hasta ahora, los dos tienen que
+// coincidir, y `reconciled` los resta. Si un día no coinciden, el diario y los saldos divergieron
+// y esto es lo primero que lo dice.
+export async function estadoDeCuenta(libro, account, { since = null, until = null, limit = null, max = 200 } = {}) {
+  const desde = fechaIso(since, 'since'), hasta = fechaIso(until, 'until');
+  if (desde && hasta && desde > hasta) throw new LibroError(400, `since (${desde}) is after until (${hasta})`);
+  const raw = Number(limit);
+  const n = Number.isInteger(raw) && raw > 0 ? Math.min(raw, max) : (desde || hasta ? max : 20);
+  const store = libro.store, casa = libro.casa;
+  const ledger = await libro.balance(account);
+  const { entries, total } = await store.libroStatementRange(account, { since: desde, until: hasta, limit: n });
+  const opening = entries.length
+    ? await store.libroBalanceBefore(account, { n: entries[0].n })
+    : (desde ? await store.libroBalanceBefore(account, { at: desde }) : 0);
+  const totals = { in: 0, out: 0, fees: 0, commissions: 0 };
+  const rows = [];
+  let saldo = opening;
+  for (const a of entries) {
+    for (const r of filasDe(a, account, casa)) {
+      saldo += r.in - r.out;
+      totals.in += r.in; totals.out += r.out; totals.fees += r.fee;
+      if (r.kind === 'commission') totals.commissions += r.out;
+      rows.push({ ...r, balance: saldo });
+    }
+  }
+  // Cuadre interno: lo que dicen las filas tiene que ser lo que dicen las líneas del diario.
+  const neto = entries.reduce((s, a) => s + a.lines.filter((l) => l.account === account).reduce((t, l) => t + l.delta, 0), 0);
+  if (opening + neto !== saldo) throw new LibroError(500, `statement does not reconcile with the journal (${opening} + ${neto} != ${saldo})`);
+  // Sin `until` la lista termina en el último asiento de la cuenta (se conservan los más
+  // recientes): el saldo final tiene que ser el saldo de hoy, esté o no truncada la lista.
+  const reconciled = hasta ? null : saldo === ledger;
+  return {
+    account, house: libro.domain, since: desde, until: hasta,
+    opening_balance: opening, entries: rows, closing_balance: saldo, totals,
+    rows: rows.length, entries_shown: entries.length, entries_total: total, truncated: total > entries.length,
+    ledger_balance: ledger, reconciled,
+  };
+}
+
+// ---------- CSV (RFC 4180) ----------
+// Un campo con coma, comillas o salto de línea va entre comillas, y las comillas se doblan.
+export function campoCsv(v) {
+  const s = v == null ? '' : String(v);
+  return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+// Texto que escribió otro agente (concepto, contraparte) y que una hoja de cálculo podría tomar
+// por fórmula: se antepone un apóstrofo, como recomienda OWASP. Los números son nuestros.
+function textoCsv(s) {
+  const t = s == null ? '' : String(s);
+  return /^[=+\-@\t\r]/.test(t) ? `'${t}` : t;
+}
+export function csvDe(estado) {
+  const num = (x) => (x ? String(x) : '');
+  const lineas = [CSV_CABECERA.join(',')];
+  for (const r of estado.entries) {
+    lineas.push([r.date, r.entry, textoCsv(r.concept), textoCsv(r.counterparty), num(r.in), num(r.out), num(r.fee), String(r.balance)].map(campoCsv).join(','));
+  }
+  return `${lineas.join('\r\n')}\r\n`;
+}
+// estado-<local>-<desde>-<hasta>.csv; sin rango: inicio / la fecha de hoy. Sólo caracteres seguros
+// para un nombre de archivo en una cabecera.
+export function nombreCsv(estado, hoy = new Date()) {
+  const [local, domain] = String(estado.account).split('@');
+  const quien = domain && domain !== estado.house ? `${local}.${domain}` : local;
+  const desde = estado.since ? estado.since.slice(0, 10) : 'inicio';
+  const hasta = estado.until ? estado.until.slice(0, 10) : hoy.toISOString().slice(0, 10);
+  return `estado-${quien}-${desde}-${hasta}.csv`.replace(/[^A-Za-z0-9._-]/g, '-');
+}

package/src/libro/informe.js

@@ -51,6 +51,119 @@ export async function datosInforme(estafeta, { dias = 7 } = {}) {
   };
 }
 
+// ---------- Embudo (NX-801): de punta a punta, por fuente y por semana ----------
+// Seis etapas, en el orden en que una persona las cruza. Cada una es UN evento del diario; el
+// informe no infiere ninguna. `open_invite` cuenta visitas al enlace (una vista previa de
+// WhatsApp también abre); las otras cinco cuentan direcciones raíz, una vez cada una.
+export const ETAPAS = [
+  { id: 'open_invite', label: 'Invite opened' },
+  { id: 'join', label: 'Address created' },
+  { id: 'claude_connected', label: 'Claude connected' },
+  { id: 'first_message', label: 'First message sent' },
+  { id: 'first_quote', label: 'First contract' },
+  { id: 'mandate_created', label: 'First mandate' },
+];
+// `connector_authorized` existía antes de NX-801 y se emite en el mismo punto que
+// `claude_connected`: leerlo como alias hace que los recorridos anteriores al despliegue (Basti,
+// 11-sep) muestren la etapa 3 en vez de un hueco. Las etapas 1 y 4 no tienen alias: antes no se
+// medían, y el informe las muestra vacías en vez de inventarlas.
+const ALIAS = { connector_authorized: 'claude_connected' };
+
+// Semana ISO-8601 (lunes a domingo, la semana 1 es la del primer jueves), en UTC como el diario.
+export function semanaIso(ts) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return null;
+  d.setUTCHours(0, 0, 0, 0);
+  d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7));
+  const primero = Date.UTC(d.getUTCFullYear(), 0, 1);
+  return `${d.getUTCFullYear()}-W${String(Math.ceil(((d - primero) / 86_400_000 + 1) / 7)).padStart(2, '0')}`;
+}
+
+// Qué lee: los `join` de siempre (son la lista de raíces y de fuentes) y todos los eventos de la
+// ventana. Qué NO cubre: un delegado cuyo nombre no termine en `.<raíz>` de una raíz conocida queda
+// en `sinRaiz`, contado y no atribuido; si el diario supera el tope, `truncado` lo dice.
+export async function datosEmbudo(estafeta, { ventanaDias = 90, semanas = 8, diasRecorridos = 30, tope = 5000 } = {}) {
+  const ahora = Date.now();
+  const desde = new Date(ahora - ventanaDias * 86_400_000).toISOString();
+  const lee = async (q) => (await estafeta.store.listEvents?.(q)) || [];
+  const [eventos, joins] = await Promise.all([lee({ since: desde, limit: tope }), lee({ name: 'join', limit: tope })]);
+
+  // Raíces conocidas: quien hizo join, y quien las etapas 3 y 4 nombran (por construcción, raíces).
+  const raices = new Set(joins.map((e) => e.actor).filter(Boolean));
+  for (const e of eventos) if (['claude_connected', 'connector_authorized', 'first_message'].includes(e.name) && e.actor) raices.add(e.actor);
+  // Un delegado se llama <nombre>.<raíz>@casa: se prueba cada sufijo hasta dar con una raíz conocida.
+  const raizDe = (dir) => {
+    if (typeof dir !== 'string' || !dir.includes('@')) return null;
+    if (raices.has(dir)) return dir;
+    const [local, dominio] = dir.split('@');
+    const partes = local.split('.');
+    for (let i = 1; i < partes.length; i++) { const c = `${partes.slice(i).join('.')}@${dominio}`; if (raices.has(c)) return c; }
+    return null;
+  };
+  const recorridos = new Map();
+  const alcanza = (raiz, etapa, ts) => {
+    const r = recorridos.get(raiz) || { address: raiz, source: null, code: null, etapas: {} };
+    if (!r.etapas[etapa] || ts < r.etapas[etapa]) r.etapas[etapa] = ts;
+    recorridos.set(raiz, r);
+    return r;
+  };
+  const sinRaiz = {};
+  const aperturas = [];
+  for (const e of joins) { const r = alcanza(e.actor, 'join', e.ts); r.source = r.source || e.data?.source || null; }
+  for (const e of eventos) {
+    const etapa = ALIAS[e.name] || e.name;
+    if (etapa === 'open_invite') { aperturas.push(e); continue; }
+    if (etapa === 'join' || !ETAPAS.some((x) => x.id === etapa)) continue;
+    // Un contrato lo alcanzan las dos partes: el actor de `first_quote` es el comprador, `seller` la otra.
+    for (const p of etapa === 'first_quote' ? [e.actor, e.data?.seller] : [e.actor]) {
+      const raiz = raizDe(p);
+      if (!raiz) { if (p) sinRaiz[etapa] = (sinRaiz[etapa] || 0) + 1; continue; }
+      const r = alcanza(raiz, etapa, e.ts);
+      if (etapa === 'claude_connected' && e.data?.code && !r.code) r.code = e.data.code;
+    }
+  }
+  // Enlace abierto -> dirección: por el código de la invitación que `claude_connected` trae. Si el
+  // join no declaró fuente, la del enlace es la atribución (así se atribuye a quien llegó por la app).
+  const porCodigo = new Map();
+  for (const a of aperturas) { const c = a.data?.code; if (c && (!porCodigo.has(c) || a.ts < porCodigo.get(c).ts)) porCodigo.set(c, a); }
+  for (const r of recorridos.values()) {
+    const a = r.code && porCodigo.get(r.code);
+    if (a) { alcanza(r.address, 'open_invite', a.ts); r.source = r.source || a.data?.source || null; }
+  }
+  const NO = '(not declared)';
+  const inc = (tabla, fila, etapa) => { const f = tabla.get(fila) || {}; f[etapa] = (f[etapa] || 0) + 1; tabla.set(fila, f); };
+
+  // Por fuente, en la ventana: aperturas por su propia fuente; direcciones cuyo join cae en la
+  // ventana (o que no tienen join registrado) por la fuente del recorrido.
+  const porFuente = new Map();
+  for (const a of aperturas) inc(porFuente, a.data?.source || NO, 'open_invite');
+  for (const r of recorridos.values()) {
+    if (r.etapas.join && r.etapas.join < desde) continue;
+    for (const etapa of Object.keys(r.etapas)) if (etapa !== 'open_invite') inc(porFuente, r.source || NO, etapa);
+  }
+  // Por semana ISO: las últimas N, la actual incluida. Cada etapa cuenta en la semana en que se alcanzó.
+  const semanasLista = [];
+  for (let i = semanas - 1; i >= 0; i--) semanasLista.push(semanaIso(ahora - i * 7 * 86_400_000));
+  const porSemana = new Map(semanasLista.map((s) => [s, {}]));
+  for (const a of aperturas) { const s = semanaIso(a.ts); if (porSemana.has(s)) inc(porSemana, s, 'open_invite'); }
+  for (const r of recorridos.values()) for (const [etapa, ts] of Object.entries(r.etapas)) { if (etapa === 'open_invite') continue; const s = semanaIso(ts); if (porSemana.has(s)) inc(porSemana, s, etapa); }
+  // Recorridos individuales: los que alcanzaron alguna etapa en los últimos N días, el más reciente primero.
+  const corte = new Date(ahora - diasRecorridos * 86_400_000).toISOString();
+  const ultima = (r) => Object.values(r.etapas).sort().at(-1) || '';
+  const recientes = [...recorridos.values()].filter((r) => ultima(r) >= corte).sort((a, b) => (ultima(a) < ultima(b) ? 1 : -1))
+    .map((r) => ({ address: r.address, source: r.source, etapas: Object.fromEntries(ETAPAS.map((x) => [x.id, r.etapas[x.id] || null])) }));
+  const fila = (t) => ETAPAS.map((x) => t[x.id] || 0);
+  return {
+    generado: new Date(ahora).toISOString(), desde, ventanaDias, semanas, diasRecorridos,
+    eventosLeidos: eventos.length, joinsLeidos: joins.length, tope, truncado: eventos.length >= tope || joins.length >= tope,
+    etapas: ETAPAS.map((x) => x.label),
+    porFuente: [...porFuente.entries()].sort((a, b) => (b[1].join || 0) - (a[1].join || 0) || (b[1].open_invite || 0) - (a[1].open_invite || 0)).map(([fuente, t]) => ({ fuente, conteos: fila(t) })),
+    porSemana: [...porSemana.entries()].map(([semana, t]) => ({ semana, conteos: fila(t) })),
+    recorridos: recientes,
+    raices: recorridos.size, sinRaiz,
+  };
+}
+
 // Las frases que interpretan los números. Cada una puede ser mala noticia, y esa es la idea.
 export function lecturas(d) {
   const L = [];
@@ -67,7 +180,31 @@ export function lecturas(d) {
   return L;
 }
 
-export function informeHtml(dominio, d) {
+// La sección privada del embudo: tablas sin JS, cada celda escapada. Sólo se arma cuando la
+// ruta privada la pide; /report nunca la recibe.
+export function embudoHtml(e) {
+  const th = (xs) => `<tr>${xs.map((x) => `<th>${esc(x)}</th>`).join('')}</tr>`;
+  const tr = (cabeza, xs) => `<tr><td class="k">${esc(cabeza)}</td>${xs.map((x) => `<td class="n">${esc(x)}</td>`).join('')}</tr>`;
+  const fecha = (ts) => (ts ? ts.slice(0, 10) : '—');
+  const tabla = (cabeza, filas) => `<div class="ancha"><table class="embudo">${th(cabeza)}${filas.join('')}</table></div>`;
+  const vacio = (texto) => `<p class="rango">${esc(texto)}</p>`;
+  return `
+  <h2>Funnel</h2>
+  <p class="rango">Private: this section names addresses. Read from the events diary at load time: ${esc(e.eventosLeidos)} events in the last ${esc(e.ventanaDias)} days and ${esc(e.joinsLeidos)} joins overall (limit ${esc(e.tope)} each${e.truncado ? ', REACHED: older events were left out' : ''}). "Invite opened" counts link visits, previews included; the other five count addresses once each. A missing stage is shown as a dash, never guessed.</p>
+
+  <h3>By source, last ${esc(e.ventanaDias)} days</h3>
+  ${e.porFuente.length ? tabla(['Source', ...e.etapas], e.porFuente.map((f) => tr(f.fuente, f.conteos))) : vacio('No joins and no invite opened in this window.')}
+
+  <h3>By ISO week, last ${esc(e.semanas)}</h3>
+  ${tabla(['Week', ...e.etapas], e.porSemana.map((s) => tr(s.semana, s.conteos)))}
+
+  <h3>Journeys, last ${esc(e.diasRecorridos)} days</h3>
+  ${e.recorridos.length ? tabla(['Address', 'Source', ...e.etapas], e.recorridos.map((r) => tr(r.address, [r.source || '(not declared)', ...ETAPAS.map((x) => fecha(r.etapas[x.id]))]))) : vacio('Nobody reached any stage in this window.')}
+  ${Object.keys(e.sinRaiz).length ? `<p class="rango">Not attributed to any known root address: ${esc(Object.entries(e.sinRaiz).map(([k, v]) => `${k} ${v}`).join(', '))}.</p>` : ''}
+`;
+}
+
+export function informeHtml(dominio, d, { embudo = null } = {}) {
   const fila = (k, v) => `<tr><td>${esc(k)}</td><td class="n">${esc(v)}</td></tr>`;
   const fuentes = Object.entries(d.porFuente).sort((a, b) => b[1] - a[1]);
   return `<!doctype html>
@@ -99,6 +236,13 @@ export function informeHtml(dominio, d) {
   li b { color:var(--ink); }
   footer { color:var(--dim); font-size:.82rem; border-top:1px solid var(--line); padding-top:1.4rem; }
   a { color:var(--accent); text-decoration:none; } a:hover { text-decoration:underline; }
+  h3 { font-size:.95rem; font-weight:600; margin:0 0 .6rem; }
+  .ancha { overflow-x:auto; margin:0 0 2rem; }
+  table.embudo { font-size:.8rem; margin:0; }
+  table.embudo th { text-align:right; font-weight:600; color:var(--dim); padding:.35rem .4rem; border-bottom:1px solid var(--line); white-space:nowrap; }
+  table.embudo th:first-child, table.embudo td.k { text-align:left; padding-left:0; }
+  table.embudo td { padding:.35rem .4rem; }
+  table.embudo td.n { font-size:.8rem; }
 </style>
 </head>
 <body>
@@ -124,9 +268,9 @@ export function informeHtml(dominio, d) {
 
   <h2>Where they came from</h2>
   ${fuentes.length ? `<table>${fuentes.map(([f, n]) => fila(f, n)).join('')}</table><p class="rango">Joins, not visits. A page view is not an agent.</p>` : '<p class="rango">Nobody joined, so there is nothing to attribute.</p>'}
-
+${embudo ? embudoHtml(embudo) : ''}
   <footer>
-    No agent names, no counterparties and no message content appear here — only how many and how much.
+    ${embudo ? 'This page is private to the house and names addresses; the public <code>/report</code> does not.' : 'No agent names, no counterparties and no message content appear here — only how many and how much.'}
     Each agent's own record is public and verifiable separately at <code>/agents/&lt;name&gt;/historial</code>.
     <br><a href="/">Home</a> · <a href="/spec">Specification</a>
   </footer>

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 };
 
@@ -35,6 +36,8 @@ export const MEDIA = {
   op: 'application/nyx5.libro+json',
   cotizacion: 'application/nyx5.cotizacion+json',
   recibo: 'application/nyx5.recibo+json',
+  // NX-305: un comprador PIDE un servicio del catálogo; el vendedor contesta con la cotización.
+  pedido: 'application/nyx5.pedido+json',
 };
 
 const iso = () => new Date().toISOString();
@@ -42,10 +45,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 +68,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 +96,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); }
@@ -114,13 +123,17 @@ export class Libro {
   //   bond   released | forfeited         afirmación sostenida | derribada
   static TERMINALES = { spot: ['settled'], escrow: ['released', 'refunded'], bond: ['released', 'forfeited'], metered: [] };
 
-  async historial(address) {
-    const todos = await this.store.libroListContracts();
+  // `contratos`: la lista ya leída, para que un lote de historiales (la ruta en lote, el rastreo
+  // del índice) no vuelva a leer la tabla por cada dirección.
+  async historial(address, { contratos = null } = {}) {
+    const todos = contratos ?? await this.store.libroListContracts();
     const mios = todos.filter((c) => [c.seller, c.buyer].includes(address));
     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 +155,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 +166,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 +196,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 +213,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 +264,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 +277,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 +299,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 +325,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 +338,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 +360,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 +372,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 } }] };
+}