@nyx5/nyx5 0.6.0 → 0.7.0

package/src/libro/contratos.js

@@ -13,8 +13,11 @@
 
 import { sha256hex, canonical, uuid } from '../nucleo/crypto.js';
 import { parseAddress } from '../correo/resolver.js';
+import { applyInboxPolicy } from '../correo/politica.js';
 
 import { LibroError } from './errores.js';
+import { estadoDeCuenta } from './estado.js';
+import { notarize } from './notaria.js';
 
 const iso = () => new Date().toISOString();
 const fail = (code, msg) => { throw new LibroError(code, msg); };
@@ -33,6 +36,36 @@ function scopeCap(ctx, amount, what) {
   if (cap != null && amount > cap) fail(403, `${what}: ${amount} tok exceeds the subagent cap of ${cap}`);
 }
 function must(cond, code, msg) { if (!cond) fail(code, msg); }
+
+// ---------- alcance de un mandato: vocabulario CERRADO, y se falla cerrado ----------
+// Un mandato es autoridad de gasto. Si el mandante escribe una restricción que el Libro no sabe
+// aplicar, la opción segura NO es guardarla y seguir: es negarse.
+//
+// Nació de un defecto real (9-sep-2026): un mandato con `max_per_charge: 500` y una lista de
+// destinatarios permitidos guardó las dos, las FIRMÓ, y después dejó pasar un cobro único de
+// 90.000. La restricción se veía al leer el mandato de vuelta y no hacía nada. Un instrumento que
+// falla hacia el ruido es peor que uno que no existe: te deja construir encima.
+//
+// Esto contradice a propósito el invariante 7 (los campos desconocidos se conservan y se ignoran).
+// Ese invariante es para MENSAJES, donde ignorar lo que no entiendes es lo que permite extender el
+// protocolo sin romperlo. Para autoridad de gasto es lo contrario: ignorar una restricción
+// autoriza MÁS de lo que el mandante quiso.
+export const ALCANCE_MANDATO = Object.freeze(['concepts', 'max_per_charge']);
+
+function validarAlcance(scope, cap) {
+  if (scope == null) return {};
+  must(typeof scope === 'object' && !Array.isArray(scope), 400, 'scope must be an object');
+  const ajenas = Object.keys(scope).filter((k) => !ALCANCE_MANDATO.includes(k));
+  must(!ajenas.length, 400, `this ledger cannot enforce ${ajenas.map((k) => JSON.stringify(k)).join(', ')} in a mandate scope, so it refuses to store it as if it could. It enforces: ${ALCANCE_MANDATO.join(', ')}`);
+  if (scope.concepts != null) {
+    must(Array.isArray(scope.concepts) && scope.concepts.every((c) => typeof c === 'string'), 400, 'scope.concepts must be a list of strings');
+  }
+  if (scope.max_per_charge != null) {
+    must(Number.isInteger(scope.max_per_charge) && scope.max_per_charge > 0, 400, 'scope.max_per_charge must be a positive integer');
+    must(cap == null || scope.max_per_charge <= cap, 400, `scope.max_per_charge (${scope.max_per_charge}) cannot exceed the mandate cap (${cap})`);
+  }
+  return scope;
+}
 const parties = (c) => [c.seller, c.buyer, c.verifier, c.arbiter].filter(Boolean);
 
 // ============ Operaciones ============
@@ -48,7 +81,7 @@ const ops = {
     const c = {
       id: uuid(), kind: q.contract, house: libro.domain, seller: q.seller, buyer: from, amount: q.price,
       concept: q.concept, terms: q.terms || {}, arbiter: q.arbiter || null, referrer: q.referrer || null,
-      quote_id: q.id, quote_sha256: sha256hex(canonical(q)), accept_sha256: ctx.opHash,
+      quote_id: q.id, quote_sha256: sha256hex(canonical(q)), accept_sha256: ctx.opHash, ...(q.service ? { service: q.service } : {}),
       state: 'accepted', created: iso(), history: [],
     };
     const refs = { contract: c.id, quote: q.id, quote_sha256: c.quote_sha256, op: ctx.env.id, op_sha256: ctx.opHash };
@@ -112,6 +145,43 @@ const ops = {
     return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
   },
 
+  // --- escrow que vence (NX-503): el comprador recupera; una entrega sin objeción se libera ---
+  // Antes un contrato vencido sólo mandaba un aviso y la plata quedaba retenida para siempre.
+  // reclaim: sólo el comprador, sólo sin entrega, y sólo pasado el plazo más la gracia de la casa.
+  async reclaim(ctx) {
+    const { libro, from, body } = ctx;
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'escrow', 409, 'reclaim only applies to escrow');
+    must(from === c.buyer, 403, 'only the buyer reclaims an expired escrow');
+    must(c.state === 'held', 409, c.state === 'delivered' ? 'the seller already delivered: refund needs the seller or the arbiter, or the review window' : `state ${c.state}`);
+    const plazo = Date.parse(c.terms?.deadline || '');
+    must(!Number.isNaN(plazo), 409, 'this escrow has no deadline: only the seller or the arbiter can refund it');
+    const desde = plazo + libro.reclaimGraceMs;
+    must(Date.now() >= desde, 409, `the deadline plus the grace period has not passed yet (reclaimable from ${new Date(desde).toISOString()})`);
+    const asiento = await libro.refund(c.id, c.buyer, c.amount, `escrow vencido ${c.id}: ${c.concept}`, { contract: c.id, kind: 'reclaim' }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    c.state = 'refunded';
+    record(libro, c, 'reclaim', from, { asiento: asiento.id, deadline: c.terms.deadline });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
+  },
+  // expire: lo firma la CASA (libro@) desde el reloj, nunca una parte. Entregado, con plazo vencido,
+  // y pasada la ventana de revisión sin que nadie devolviera ni liberara: se libera al vendedor.
+  // «Sin disputa» quiere decir que ni el comprador ni el árbitro hicieron refund en la ventana.
+  async expire(ctx) {
+    const { libro, from, body } = ctx;
+    must(from === libro.address, 403, 'only the house settles an expired escrow');
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'escrow' && c.state === 'delivered', 409, `state ${c.state}, expected a delivered escrow`);
+    const plazo = Date.parse(c.terms?.deadline || '');
+    must(!Number.isNaN(plazo), 409, 'no deadline: a delivery without a deadline waits for the buyer or the arbiter');
+    const entregado = Date.parse(c.history.findLast?.((h) => h.op === 'deliver')?.at || c.history.filter((h) => h.op === 'deliver').at(-1)?.at || '');
+    const desde = Math.max(plazo, entregado || 0) + libro.reviewWindowMs;
+    must(Date.now() >= desde, 409, `the review window is still open (until ${new Date(desde).toISOString()})`);
+    const asiento = await libro.release(c.id, c.seller, c.amount, `liberación por ventana vencida ${c.id}: ${c.concept}`, { contract: c.id, kind: 'expire' }, { op: ctx.env.id, op_sha256: ctx.opHash }, c.referrer);
+    c.state = 'released';
+    record(libro, c, 'expire', from, { asiento: asiento.id, review_until: new Date(desde).toISOString() });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento, note: 'delivered, deadline passed, not refunded within the review window: released by the house clock' } }] };
+  },
+
   // --- fianza: el que afirma deposita; si la verificación lo derriba, la pierde ---
   async bond(ctx) {
     const { libro, from, body } = ctx;
@@ -161,7 +231,7 @@ const ops = {
       must(body.cap <= parent.cap - parent.spent, 403, `the sub-mandate (${body.cap}) exceeds what the parent has left (${parent.cap - parent.spent})`);
       if (parent.expires) must(!body.expires || Date.parse(body.expires) <= Date.parse(parent.expires), 403, 'the sub-mandate cannot outlast its parent');
     }
-    const m = { id: uuid(), house: libro.domain, grantor: from, grantee: body.grantee, cap: body.cap, spent: 0, scope: body.scope || {}, expires: body.expires || parent?.expires || null,
+    const m = { id: uuid(), house: libro.domain, grantor: from, grantee: body.grantee, cap: body.cap, spent: 0, scope: validarAlcance(body.scope, body.cap), expires: body.expires || parent?.expires || null,
       parent: parent?.id || null, root: parent ? parent.root : from, chain: [], state: 'active', created: iso(), op_sha256: ctx.opHash };
     m.chain = parent ? [...parent.chain, m.id] : [m.id];
     libro.putMandate(m);
@@ -180,7 +250,14 @@ const ops = {
       must(cur.state === 'active', 409, `mandate ${cur.id} is not active`);
       must(!cur.expires || Date.parse(cur.expires) > Date.now(), 410, `mandato ${cur.id} vencido`);
       must(cur.cap - cur.spent >= body.amount, 402, `mandate ${cur.id}: ${cur.cap - cur.spent} left, ${body.amount} requested`);
+      // Fallar cerrado: un mandato guardado ANTES de este candado puede llevar una restricción que
+      // no sabemos aplicar. No se cobra contra él hasta que su mandante lo rehaga.
+      const ajenas = Object.keys(cur.scope || {}).filter((k) => !ALCANCE_MANDATO.includes(k));
+      must(!ajenas.length, 403, `mandate ${cur.id} carries ${ajenas.map((k) => JSON.stringify(k)).join(', ')} in its scope, which this ledger cannot enforce; it refuses to charge against a limit it cannot apply`);
       if (cur.scope?.concepts?.length) must(cur.scope.concepts.includes(body.concept), 403, `concept "${body.concept}" is outside the mandate scope`);
+      // Tope por cobro: el total ya no se puede vaciar de un solo golpe. Se comprueba en CADA
+      // eslabón, así que el tope del padre acota lo que cobra el nieto.
+      if (cur.scope?.max_per_charge != null) must(body.amount <= cur.scope.max_per_charge, 403, `mandate ${cur.id} caps a single charge at ${cur.scope.max_per_charge}, and ${body.amount} was requested`);
       chain.push(cur);
     }
     // El descuento de la cadena y el asiento van en la MISMA transacción: si el commit falla,
@@ -202,22 +279,54 @@ const ops = {
     return { result: { revoked: affected.map((x) => x.id) }, recibos: [{ to: [...new Set(affected.flatMap((x) => [x.grantor, x.grantee]))], thread: m.chain[0], body: { revoked: affected.map((x) => x.id), by: from } }] };
   },
 
+  // --- pagar directo: sin cotización ni contrato. Lo firma el que paga; el que recibe no hace nada.
+  // Es el "te mando plata" entre dos personas. Sólo dentro de la casa: aquí no hay cómo comprobar
+  // que una dirección de otra casa existe, y un pago a nadie deja tokens varados para siempre.
+  async pay(ctx) {
+    const { libro, from, body } = ctx;
+    let to; try { to = parseAddress(body.to); } catch { fail(400, 'pay needs "to": the address that receives'); }
+    const address = `${to.local}@${to.domain}`;
+    must(to.domain === libro.domain, 400, `pay moves tokens inside ${libro.domain}; ${to.domain} keeps its own ledger`);
+    must(address !== from, 400, 'paying yourself moves nothing');
+    must(Number.isSafeInteger(body.amount) && body.amount > 0, 400, 'amount must be a positive integer');
+    scopeCap(ctx, body.amount, 'paying');
+    const rec = await libro.store.getAgent(to.local);
+    must(rec && !rec.revoked, 404, `${address} does not exist in this house`);
+    // Un subagente de sólo mensajes nunca podrá gastar: lo que le llegue quedaría varado. Se le paga al dueño.
+    must(!rec.delegation?.scope?.messages_only, 400, `${address} only carries messages and could never spend this; pay its owner, ${rec.delegation?.by}`);
+    const concept = typeof body.concept === 'string' && body.concept.trim() ? body.concept.trim().slice(0, 200) : `pago de ${from}`;
+    // Sin fee (decidido por Nicholas el 11-sep-2026): mandarle tokens a una persona es gratis, como un
+    // mensaje. El fee de la casa (0,5%) es para el trabajo que alguien encarga: spot, escrow, mandatos.
+    const asiento = await libro.post(concept, [{ account: from, delta: -body.amount }, { account: address, delta: body.amount }], { kind: 'pay', to: address, fee: 0 }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    // El aviso al que recibe obedece a su buzón, como si el pagador le escribiera. Defecto real
+    // (revisión del 11-sep-2026): con pay sin fee, un pago de 1 token dejaba un sobre de libro@ en un
+    // buzón que cobra 500 por mensaje. El pago ocurre igual y el saldo lo muestra; el aviso no pasa.
+    const p = applyInboxPolicy({ from, to: [address], type: 'receipt' }, rec, null);
+    const avisar = p.ok === true && (!p.stamp || body.amount >= p.stamp.price);
+    return { result: { asiento, notified: avisar }, recibos: [{ to: avisar ? [from, address] : [from], body: { asiento, pay: { from, to: address, amount: body.amount, concept } } }] };
+  },
+
   // --- lecturas: la respuesta vuelve por correo como recibo ---
   async balance(ctx) {
     const acc = await ctx.libro.account(ctx.from);
     return { result: acc, recibos: [{ to: [ctx.from], body: { account: acc.account, balance: acc.balance, contracts: acc.contracts.length, mandates: acc.mandates.length } }] };
   },
+  // Estado de cuenta (NX-501): `since`/`until` ISO-8601 acotan el rango, `limit` cuántos asientos
+  // (tope 200 por correo: el recibo viaja en un sobre). Devuelve saldo inicial, filas (fee y
+  // comisión como filas propias), saldo final y totales que cuadran. Ver estado.js.
   async statement(ctx) {
-    const raw = Number(ctx.body.limit);
-    const n = Number.isInteger(raw) && raw > 0 ? Math.min(raw, 200) : 20;
-    const entries = await ctx.libro.store.libroStatement(ctx.from, n);
-    return { result: { entries }, recibos: [{ to: [ctx.from], body: { entries } }] };
+    const { since, until, limit } = ctx.body;
+    const estado = await estadoDeCuenta(ctx.libro, ctx.from, { since, until, limit, max: 200 });
+    return { result: estado, recibos: [{ to: [ctx.from], body: estado }] };
   },
   async contract(ctx) {
     const c = await getContract(ctx.libro, ctx.body.contract);
     must(parties(c).includes(ctx.from), 403, 'you are not a party to this contract');
     return { result: { contract: c }, recibos: [{ to: [ctx.from], thread: c.id, body: { contract: c } }] };
   },
+
+  // --- notaría (NX-601): sellar el hash de un documento con fecha y firma de la casa. Sin dinero.
+  notarize,
 };
 
 // ============ Tipos de contrato cotizables ============
@@ -235,7 +344,7 @@ export const CONTRATOS = {
   } },
   // Medido: la aceptación crea un mandato del comprador al vendedor con tope = precio cotizado.
   metered: { quoteable: true, async onAccept({ libro, c, q, refs }) {
-    const m = { id: uuid(), house: libro.domain, grantor: c.buyer, grantee: c.seller, cap: c.amount, spent: 0, scope: q.terms?.scope || {}, expires: q.terms?.expires || q.expires || null,
+    const m = { id: uuid(), house: libro.domain, grantor: c.buyer, grantee: c.seller, cap: c.amount, spent: 0, scope: validarAlcance(q.terms?.scope, c.amount), expires: q.terms?.expires || q.expires || null,
       parent: null, root: c.buyer, chain: [], state: 'active', created: iso(), contract: c.id, op_sha256: refs.op_sha256 };
     m.chain = [m.id];
     libro.putMandate(m);

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>