@nyx5/nyx5 0.6.0 → 0.8.0

package/src/correo/ci.js

@@ -0,0 +1,262 @@
+// Nyx5/1 — El EJECUTOR: el aviso de la casa hacia CI, para los roles que trabajan sobre archivos.
+//
+// Por qué existe (NX-412, 27-oct-2026). `asistente.js` + `acciones.js` despiertan a los agentes que
+// PIENSAN: viven en el Worker, contestan solos y sus cinco manos no tocan un disco. Un rol de la
+// fábrica de Rosetta no cabe ahí: lee un repositorio, escribe archivos, corre python. Medido con
+// Rosetta: 7 de sus 8 roles ejecutan. Para esos, la casa no hace el trabajo — AVISA a un ejecutor
+// de fuera (hoy, un workflow de GitHub Actions) y el ejecutor contesta firmando con la llave del
+// propio rol, que vive en los secrets de CI y nunca pasa por la casa ni por el chat.
+//
+// Tres decisiones que no son detalle:
+//
+// 1. **El aviso NO lleva el contenido.** Viaja sólo el sobre: quién escribió, qué tipo, qué
+//    proyecto, su id y la firma de la casa. El cuerpo va cifrado y lo abre el ejecutor con la llave
+//    del rol, leyendo `GET /mailbox/<local>` como cualquier agente. Así el invariante 8 queda
+//    intacto y el texto de un encargo no aparece en el registro de un tercero (el payload de un
+//    `repository_dispatch` queda en la pantalla de Actions, legible para quien tenga el repo).
+//
+// 2. **El destino se DERIVA, nunca se recibe.** La casa guarda un token con permiso de disparar CI;
+//    si además aceptara una URL libre, sería un diputado confundido que manda ese token a donde le
+//    digan. `PROVEEDORES` es una lista CERRADA, la URL se arma del `repo` validado por sintaxis, y
+//    el token no vuelve por ninguna lectura (como los secrets de Cloudflare: se rota, no se lee).
+//
+// 3. **El aviso no se cierra el sobre.** La casa avisa; el sobre sigue pendiente hasta que el
+//    ejecutor lo confirme. Un despacho perdido se reintenta con espera creciente y, agotados los
+//    intentos, el dueño recibe un aviso NOMBRADO: el `task` que estuvo seis semanas en silencio en
+//    el buzón de qa@ nació justo de un camino que fallaba sin decirlo.
+
+import { parseAddress } from './resolver.js';
+import { esEncargo, porGrupo } from './asistente.js';
+import { signBytes } from '../nucleo/crypto.js';
+import { proyectoDe } from './politica.js';
+
+// Direcciones de sistema de esta casa: sus recibos y rebotes no son un encargo.
+const SISTEMA = new Set(['postmaster', 'libro', 'verifica', 'tareas']);
+// Los tipos que son «te encargo esto» o su resultado. Lo demás no despierta a un ejecutor.
+export const TIPOS_DESPACHADOS = Object.freeze(['message', 'task', 'result']);
+// Despachos por dirección y día UTC. Cada despacho arranca un job de CI, o sea PLATA: el cupo es
+// el freno, igual que el tope mensual lo es para un cerebro.
+export const CUPO_DESPACHOS_DIA = 20;
+// Intentos por sobre y espera antes de cada reintento (el primero sale al entregar, sin esperar).
+export const INTENTOS = 3;
+export const ESPERAS = Object.freeze([60_000, 300_000, 1_500_000]);
+// Lo que se guarda de un despacho fallido, recortado: un cuerpo de error ajeno no crece sin tope.
+const RAZON_MAX = 300;
+
+const REPO = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const EVENTO = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+const dia = (ms) => new Date(ms).toISOString().slice(0, 10);
+
+// Un token de CI no se cita nunca, ni en un log ni en el estado de un despacho. Nació de una
+// lección medida en el pagador x402: un error que repetía la llave malformada entregaba 72 bits
+// del secreto. Aquí el riesgo es el cuerpo que devuelve el proveedor, que no controlamos.
+export function sinSecretos(texto, token = null) {
+  const crudo = String(texto == null ? '' : texto);
+  // El valor exacto primero: la redacción por FORMA no conoce la del token de un proveedor nuevo.
+  return (token ? crudo.split(String(token)).join('[token]') : crudo)
+    .replace(/gh[pousr]_[A-Za-z0-9_]{10,}/g, '[token]')
+    .replace(/github_pat_[A-Za-z0-9_]{10,}/g, '[token]')
+    .replace(/\bBearer\s+\S+/gi, 'Bearer [token]')
+    .slice(0, RAZON_MAX);
+}
+
+// La lista CERRADA de proveedores. Agregar uno es una decisión, no una configuración: se le da a la
+// casa un token con permiso de arrancar trabajo, y el host al que ese token puede viajar se escribe
+// aquí o no existe.
+export const PROVEEDORES = Object.freeze({
+  github: Object.freeze({
+    url: (cfg) => `https://api.github.com/repos/${cfg.repo}/dispatches`,
+    cabeceras: (token) => ({
+      accept: 'application/vnd.github+json',
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json',
+      'user-agent': 'nyx5/1',
+      'x-github-api-version': '2022-11-28',
+    }),
+    cuerpo: (cfg, aviso) => JSON.stringify({ event_type: cfg.event_type, client_payload: aviso }),
+    ok: (status) => status === 204,
+  }),
+});
+
+// Valida la configuración de un ejecutor. Falla CERRADO: lo que no se entiende no se guarda, y un
+// campo ajeno se NOMBRA en vez de ignorarse — es autoridad de gasto, no un mensaje (el mismo
+// motivo por el que `ALCANCE_MANDATO` es un vocabulario cerrado y contradice el invariante 7).
+export function validarConfig(b = {}, previa = null) {
+  const conocidos = new Set(['provider', 'repo', 'event_type', 'owner', 'cupo_dia', 'enabled', 'token']);
+  const ajenos = Object.keys(b).filter((k) => !conocidos.has(k));
+  if (ajenos.length) return { error: `unknown field(s) for an executor: ${ajenos.join(', ')}. This house applies: ${[...conocidos].join(', ')}` };
+
+  const provider = b.provider ?? previa?.provider;
+  if (!provider || !Object.hasOwn(PROVEEDORES, provider)) {
+    return { error: `provider must be one of: ${Object.keys(PROVEEDORES).join(', ')}` };
+  }
+  const repo = String(b.repo ?? previa?.repo ?? '');
+  if (!REPO.test(repo) || repo.includes('..')) return { error: 'repo must be owner/name (letters, digits, dot, dash, underscore)' };
+  const event_type = String(b.event_type ?? previa?.event_type ?? 'nyx5');
+  if (!EVENTO.test(event_type)) return { error: 'event_type must be lowercase letters, digits, dot, dash or underscore (max 100)' };
+  const owner = String(b.owner ?? previa?.owner ?? '').toLowerCase();
+  try { if (!owner || !parseAddress(owner)) return { error: 'owner must be the address that gets told when CI never takes the work' }; }
+  catch { return { error: 'owner must be the address that gets told when CI never takes the work' }; }
+  const cupo = b.cupo_dia ?? previa?.cupo_dia ?? CUPO_DESPACHOS_DIA;
+  if (!Number.isInteger(cupo) || cupo < 1 || cupo > 500) return { error: 'cupo_dia must be a whole number between 1 and 500' };
+  if (b.enabled != null && typeof b.enabled !== 'boolean') return { error: 'enabled must be true or false' };
+  if (b.token != null && (typeof b.token !== 'string' || !b.token.trim() || b.token.length > 500)) {
+    return { error: 'token must be a non-empty string of at most 500 characters' };
+  }
+  if (!previa && !b.token) return { error: 'a token is needed to dispatch: it is write-only, it is never read back' };
+  return { provider, repo, event_type, owner, cupo_dia: cupo };
+}
+
+export function urlDe(cfg) { return PROVEEDORES[cfg.provider].url(cfg); }
+
+// El aviso: nueve campos. `client_payload` de GitHub admite diez propiedades de primer nivel, y el
+// décimo que podría faltar no vale lo que costaría (el contenido no viaja: ver cabecera).
+export function avisoDe(est, local, env) {
+  const to = `${local}@${est.domain}`;
+  return {
+    nyx5: '1',
+    house: est.domain,
+    to,
+    envelope: env.id,
+    from: env.from,
+    type: env.type || 'message',
+    project: proyectoDe(env) || '',
+    at: env.created || new Date().toISOString(),
+    // La firma viaja DENTRO del payload porque un `repository_dispatch` no conserva cabeceras: es lo
+    // que deja al workflow comprobar que el disparo salió de esta casa y no de cualquiera con el token.
+    sig: signBytes(`ci:${env.id}:${to}`, est.keys),
+  };
+}
+
+// ¿Este sobre despierta a un ejecutor? Las razones son las mismas que ya filtran a un cerebro
+// (revisiones del 13-sep y del 26-oct), por los mismos motivos: cada despacho arranca un job que se
+// paga, y lo que la lista del buzón no eligió no manda trabajo.
+export function despachable(est, local, rec, m) {
+  const env = m?.envelope || {};
+  // Correo que entró por el puente: sin firma no se sabe quién pide. No se despacha y no se cierra.
+  if (!env.signature || m.from_verified === false) return false;
+  let de; try { de = parseAddress(env.from); } catch { return false; }
+  if (de.domain === est.domain && SISTEMA.has(de.local)) return false;
+  // Un grupo despierta sólo si lo que llegó es un ENCARGO, y el criterio es UNA función compartida
+  // con el cerebro (`esEncargo` en asistente.js): dos definiciones de «esto es un encargo» se
+  // separan en cuanto alguien toque una, y entonces el mismo sobre despierta a un cerebro y no a un
+  // ejecutor. Lo cruza una prueba.
+  if (porGrupo(env) && !esEncargo(env)) return false;
+  if (!TIPOS_DESPACHADOS.includes(env.type)) return false;
+  if (env.from === `${local}@${est.domain}`) return true; // un recordatorio propio: despertarse a sí mismo
+  // Un `intro` de 4 KB o un avalado entran a un buzón por lista SIN estar en la lista (§9).
+  if (rec?.inbox?.policy === 'allowlist') {
+    const lista = new Set((rec.inbox.allowlist || []).filter((x) => typeof x === 'string').map((x) => x.toLowerCase()));
+    if (!lista.has(String(env.from).toLowerCase()) && !lista.has(de.domain)) return false;
+  }
+  return true;
+}
+
+// Despacha UN sobre. Devuelve `{ ok, status, reason, skipped }`. No confirma el sobre: eso es del
+// ejecutor. El cupo se cobra al DESPACHAR (no al mirar: el cupo de despertares se gastaba sin
+// despertar a nadie, medido el 26-oct) y el turno es por intento, para que dos relojes —dos
+// isolates del edge— no arranquen dos veces el mismo job.
+export async function despachar(est, local, env, { cfg = null, nowMs = Date.now() } = {}) {
+  const conf = cfg || await est.store.kvGet('ci', local);
+  if (!conf?.enabled) return { ok: false, skipped: 'disabled' };
+  const clave = `${local}:${env.id}`;
+  const estado = await est.store.kvGet('ci-despacho', clave);
+  if (estado?.estado === 'ok') return { ok: false, skipped: 'already dispatched' };
+  const intentos = Number(estado?.intentos || 0);
+  if (intentos >= INTENTOS) return { ok: false, skipped: 'attempts exhausted' };
+  // Un turno por (sobre, intento): dos relojes que vean el mismo pendiente no disparan dos jobs.
+  if (!await est.store.kvPutIfAbsent('ci-turno', `${clave}:${intentos}`, { at: new Date(nowMs).toISOString() }, nowMs + 15 * 60_000, nowMs)) {
+    return { ok: false, skipped: 'another clock took this turn' };
+  }
+  // El token ANTES del cupo: sin token no sale nada a la red, así que cobrar el despacho del día
+  // sería gastar el freno de plata en algo que nunca pasó.
+  const sello = await est.store.kvGet('boveda', `ci:${local}`);
+  let token = null;
+  try { token = est.boveda && sello ? est.boveda.abrir(sello.sellado, `ci:${local}`).token : null; } catch { token = null; }
+  if (!token) {
+    const razon = 'this house has no readable CI token for that address';
+    await est.store.kvPut('ci-despacho', clave, { intentos: INTENTOS, ultimo: new Date(nowMs).toISOString(), estado: 'fallo', razon }, nowMs + 7 * 24 * 3600_000);
+    await avisarAgotado(est, local, env, conf, razon);
+    return { ok: false, reason: razon };
+  }
+
+  const cupoClave = `${local}:${dia(nowMs)}`;
+  const usado = await est.store.kvIncrement('ci-cupo', cupoClave, nowMs + 36 * 3600_000, nowMs, 1);
+  if (usado > conf.cupo_dia) {
+    const razon = `the daily dispatch quota (${conf.cupo_dia}) for ${dia(nowMs)} is used up`;
+    await est.store.kvPut('ci-despacho', clave, { intentos, ultimo: new Date(nowMs).toISOString(), estado: 'cupo', razon }, nowMs + 7 * 24 * 3600_000);
+    est.log(`ci ${local}: ${razon}`);
+    return { ok: false, skipped: 'quota', reason: razon };
+  }
+
+  const prov = PROVEEDORES[conf.provider];
+  let status = 0, razon = '';
+  try {
+    const r = await est.fetch(urlDe(conf), {
+      method: 'POST',
+      headers: prov.cabeceras(token),
+      body: prov.cuerpo(conf, avisoDe(est, local, env)),
+      signal: AbortSignal.timeout(10_000),
+    });
+    status = r.status || 0;
+    if (!prov.ok(status)) razon = sinSecretos(`${status} ${await r.text().catch(() => '')}`, token);
+  } catch (e) {
+    razon = sinSecretos(`${e.message}${e.cause?.message ? ` / ${e.cause.message}` : ''}`, token);
+  }
+  const ok = !razon;
+  const nuevos = intentos + 1;
+  await est.store.kvPut('ci-despacho', clave, {
+    intentos: nuevos, ultimo: new Date(nowMs).toISOString(), estado: ok ? 'ok' : 'fallo', status, razon,
+  }, nowMs + 7 * 24 * 3600_000);
+  if (ok) {
+    est.log(`ci ${local}: sobre ${env.id} despachado a ${conf.provider} ${conf.repo} (${conf.event_type})`);
+    await est._evento?.('ci_dispatched', `${local}@${est.domain}`, { provider: conf.provider, repo: conf.repo, envelope: env.id });
+  } else {
+    est.log(`ci ${local}: despacho ${nuevos}/${INTENTOS} del sobre ${env.id} falló: ${razon}`);
+    if (nuevos >= INTENTOS) await avisarAgotado(est, local, env, conf, razon);
+  }
+  return { ok, status, reason: razon || undefined };
+}
+
+// Agotados los intentos, el dueño se entera. Un sobre que nadie toma no se queda en silencio: es
+// exactamente el defecto que costó seis semanas en el buzón de qa@. El aviso se reserva con
+// `kvPutIfAbsent` para que dos relojes no manden dos.
+async function avisarAgotado(est, local, env, conf, razon) {
+  if (!await est.store.kvPutIfAbsent('ci-aviso', `${local}:${env.id}`, { at: new Date().toISOString() }, Date.now() + 30 * 24 * 3600_000)) return;
+  await est._systemSend('postmaster', [conf.owner], {
+    type: 'message',
+    thread: env.thread || env.id,
+    content: {
+      media: 'text/plain',
+      body: `The executor of ${local}@${est.domain} never took envelope ${env.id} from ${env.from}. ${INTENTOS} dispatches to ${conf.provider} ${conf.repo} failed: ${razon}. The envelope is still in the mailbox, unanswered; nothing was lost. Fix the executor or the token and dispatch it again with POST /admin/executors/${local}/dispatch.`,
+    },
+  }).catch((e) => est.log(`ci ${local}: no se pudo avisar a ${conf.owner}: ${e.message}`));
+}
+
+// El reloj: recorre los ejecutores encendidos y reintenta lo que no se despachó. El primer intento
+// sale al entregar (desde `_push`); esto es la red que atrapa lo que se perdió.
+export async function atenderEjecutores(est, { nowMs = Date.now(), maxPorTick = 20 } = {}) {
+  if (!est.store.kvGet) return 0;
+  const indice = (await est.store.kvGet('ci', '_indice')) || [];
+  let n = 0;
+  for (const local of indice) {
+    const cfg = await est.store.kvGet('ci', local);
+    if (!cfg?.enabled) continue;
+    const rec = await est.store.getAgent(local);
+    if (!rec || rec.revoked) continue;
+    for (const m of await est.store.listMail(local)) {
+      if (n >= maxPorTick) return n;
+      const env = m.envelope || {};
+      if (!despachable(est, local, rec, m)) continue;
+      const estado = await est.store.kvGet('ci-despacho', `${local}:${env.id}`);
+      if (estado?.estado === 'ok') continue;
+      const intentos = Number(estado?.intentos || 0);
+      if (intentos >= INTENTOS) continue;
+      // La espera crece con el número de intentos: un CI caído no se golpea cada minuto.
+      if (intentos > 0 && nowMs - Date.parse(estado?.ultimo || 0) < ESPERAS[Math.min(intentos - 1, ESPERAS.length - 1)]) continue;
+      const r = await despachar(est, local, env, { cfg, nowMs });
+      if (!r.skipped) n++;
+    }
+  }
+  return n;
+}

package/src/correo/cobro.js

@@ -0,0 +1,164 @@
+// Nyx5/1 — Pedido de pago por transferencia (NX-502): dinero REAL, fuera del Libro.
+//
+// Un agente le pide a otro una transferencia bancaria (Chile: CLP o USD) con un sobre CIFRADO cuyo
+// contenido es el cobro: monto, moneda, nombre, RUT, banco, tipo y número de cuenta, referencia.
+// Quien pagó contesta con una confirmación (la referencia bancaria) en el hilo del pedido.
+//
+// Tres reglas que este módulo hace cumplir y que no se relajan:
+//   1. Los datos bancarios NUNCA pasan por la casa en claro: el sobre va cifrado (`encrypt: 'required'`)
+//      y jamás a una dirección cuya llave guarda la casa (`custody.keys = house`), porque la casa
+//      descifraría en su nombre. Tampoco se guardan en la tarjeta ni en la ficha: cada pedido los lleva.
+//   2. La casa NO mueve dinero ni lo ve: anota `payment_requested` / `payment_confirmed` como eventos
+//      (instrumentación) a partir de una extensión firmada EN CLARO que sólo lleva `{ kind, request_id,
+//      currency }`. Ni monto ni cuenta: `eventoDeCobro` copia campo por campo, no el objeto.
+//   3. El RUT se valida aquí (módulo 11) y en la app: la casa no puede hacerlo porque va cifrado
+//      (invariante 8). Falla CERRADO ante cualquier carácter que no sea dígito, punto, guion o K.
+//
+// Los textos de `TEXTOS` los aprobó Nicholas el 14-sep-2026 (plan/textos-app-borrador.md, NX-502):
+// se usan literales en la app y en la herramienta. Los demás mensajes de validación los lee un
+// modelo (herramienta MCP) o un formulario que ya acota el campo; no son texto aprobado.
+
+import { limpio } from './politica.js';
+
+export const MEDIA_COBRO = 'application/nyx5.cobro+json';
+export const MEDIA_COBRO_CONFIRMACION = 'application/nyx5.cobro-confirmacion+json';
+// Extensión en claro, firmada por el remitente: lo único del cobro que la casa ve.
+export const EXT_COBRO = 'urn:nyx5:ext:cobro';
+export const MONEDAS = ['CLP', 'USD'];
+export const TIPOS_CUENTA = ['checking', 'savings', 'vista'];
+export const EVENTOS_COBRO = { request: 'payment_requested', confirmation: 'payment_confirmed' };
+
+// Textos aprobados (14-sep-2026). No se cambian sin volver a mostrarlos.
+export const TEXTOS = {
+  rut: 'RUT looks wrong (check the digit).',
+  monto_clp: 'Amount must be a whole number of pesos.',
+};
+
+const LIMITES = { name: 120, bank: 60, account_number: 30, reference: 140, bank_reference: 80 };
+const ID_PEDIDO = /^[A-Za-z0-9._:-]{8,128}$/;
+
+// ---------- RUT ----------
+// Dígito verificador, módulo 11: multiplicadores 2..7 de derecha a izquierda; 11 -> 0, 10 -> K.
+export function digitoVerificador(cuerpo) {
+  let suma = 0, m = 2;
+  for (let i = cuerpo.length - 1; i >= 0; i--) { suma += Number(cuerpo[i]) * m; m = m === 7 ? 2 : m + 1; }
+  const r = 11 - (suma % 11);
+  return r === 11 ? '0' : r === 10 ? 'K' : String(r);
+}
+// Normaliza `12.345.678-5`, `12345678-5`, `123456785` a `12345678-5`; null si no es un RUT válido.
+// Sólo se aceptan dígitos, puntos, un guion y K: un carácter de control o invisible NO se limpia,
+// invalida (un RUT con basura adentro no es un RUT con el que alguien pueda transferir).
+export function normalizarRut(rut) {
+  if (typeof rut !== 'string') return null;
+  const s = rut.trim().toUpperCase().replace(/\./g, '');
+  const m = /^(\d{7,8})-?([0-9K])$/.exec(s);
+  if (!m) return null;
+  const [, cuerpo, dv] = m;
+  return digitoVerificador(cuerpo) === dv ? `${cuerpo}-${dv}` : null;
+}
+export const rutValido = (rut) => normalizarRut(rut) !== null;
+// Para mostrar: `12.345.678-5`.
+export function formatearRut(rut) {
+  const n = normalizarRut(rut); if (!n) return String(rut ?? '');
+  const [cuerpo, dv] = n.split('-');
+  return `${cuerpo.replace(/\B(?=(\d{3})+(?!\d))/g, '.')}-${dv}`;
+}
+
+// ---------- monto ----------
+// CLP: entero en pesos (número o texto de dígitos). USD: texto con hasta dos decimales.
+// Devuelve el monto normalizado (CLP: Number; USD: string como "12.50") o null.
+export function normalizarMonto(amount, currency) {
+  const s = typeof amount === 'number' ? (Number.isFinite(amount) ? String(amount) : '') : typeof amount === 'string' ? amount.trim() : '';
+  if (currency === 'CLP') {
+    if (!/^\d{1,15}$/.test(s)) return null;
+    const n = Number(s);
+    return Number.isSafeInteger(n) && n > 0 ? n : null;
+  }
+  if (currency === 'USD') {
+    if (!/^\d{1,15}(\.\d{1,2})?$/.test(s)) return null;
+    return Number(s) > 0 ? s : null;
+  }
+  return null;
+}
+
+// ---------- el pedido ----------
+// { ok: true, cobro } con todos los campos normalizados, o { ok: false, field, error }.
+export function validarCobro(x) {
+  const mal = (field, error) => ({ ok: false, field, error });
+  if (!x || typeof x !== 'object' || Array.isArray(x)) return mal('cobro', 'the payment request must be an object');
+  const currency = typeof x.currency === 'string' ? x.currency.trim().toUpperCase() : 'CLP';
+  if (!MONEDAS.includes(currency)) return mal('currency', `currency must be one of ${MONEDAS.join(', ')}`);
+  const amount = normalizarMonto(x.amount, currency);
+  if (amount === null) return mal('amount', currency === 'CLP' ? TEXTOS.monto_clp : 'Amount must be a number of dollars with up to two decimals.');
+  const rut = normalizarRut(x.rut);
+  if (!rut) return mal('rut', TEXTOS.rut);
+  const texto = (k, requerido) => {
+    const v = x[k] == null ? '' : typeof x[k] === 'string' ? limpio(x[k], LIMITES[k] + 1) : null;
+    if (v === null) return { error: `${k} must be text` };
+    if (requerido && !v) return { error: `${k} is required` };
+    if (v.length > LIMITES[k]) return { error: `${k}: up to ${LIMITES[k]} characters` };
+    return { v };
+  };
+  const name = texto('name', true); if (name.error) return mal('name', name.error);
+  const bank = texto('bank', true); if (bank.error) return mal('bank', bank.error);
+  const account_type = typeof x.account_type === 'string' ? x.account_type.trim().toLowerCase() : '';
+  if (!TIPOS_CUENTA.includes(account_type)) return mal('account_type', `account_type must be one of ${TIPOS_CUENTA.join(', ')}`);
+  const account_number = typeof x.account_number === 'string' || typeof x.account_number === 'number' ? String(x.account_number).replace(/\s+/g, '') : '';
+  if (!/^[0-9-]{1,30}$/.test(account_number)) return mal('account_number', 'account_number: digits and dashes, up to 30 characters');
+  const reference = texto('reference', false); if (reference.error) return mal('reference', reference.error);
+  let request_id = x.request_id == null ? undefined : x.request_id;
+  if (request_id !== undefined && (typeof request_id !== 'string' || !ID_PEDIDO.test(request_id))) return mal('request_id', 'request_id must be [A-Za-z0-9._:-]{8,128}');
+  return { ok: true, cobro: { ...(request_id ? { request_id } : {}), amount, currency, name: name.v, rut, bank: bank.v, account_type, account_number, reference: reference.v } };
+}
+// Igual que validarCobro, pero lanza: para el cliente y la herramienta.
+export function cobroValido(x) {
+  const r = validarCobro(x);
+  if (!r.ok) throw Object.assign(new Error(r.error), { field: r.field });
+  return r.cobro;
+}
+
+// ---------- la confirmación ----------
+export function validarConfirmacion(x) {
+  const mal = (field, error) => ({ ok: false, field, error });
+  if (!x || typeof x !== 'object' || Array.isArray(x)) return mal('confirmacion', 'the confirmation must be an object');
+  if (typeof x.request_id !== 'string' || !ID_PEDIDO.test(x.request_id)) return mal('request_id', 'request_id must be [A-Za-z0-9._:-]{8,128}');
+  const bank_reference = typeof x.bank_reference === 'string' ? limpio(x.bank_reference, LIMITES.bank_reference + 1) : null;
+  if (bank_reference === null || !bank_reference) return mal('bank_reference', 'bank_reference is required');
+  if (bank_reference.length > LIMITES.bank_reference) return mal('bank_reference', `bank_reference: up to ${LIMITES.bank_reference} characters`);
+  return { ok: true, confirmacion: { request_id: x.request_id, bank_reference } };
+}
+export function confirmacionValida(x) {
+  const r = validarConfirmacion(x);
+  if (!r.ok) throw Object.assign(new Error(r.error), { field: r.field });
+  return r.confirmacion;
+}
+
+// ---------- lo que la casa ve ----------
+// La extensión en claro que viaja firmada con el sobre. Sólo tres campos, y ninguno es dinero.
+export function extensionDeCobro(kind, { request_id, currency }) {
+  return { [EXT_COBRO]: { kind, request_id, currency } };
+}
+// El evento que la casa anota al recibir un sobre con la extensión: { name, data } o null si la
+// extensión no tiene la forma exacta. Se copian los campos UNO A UNO: si el remitente mete
+// `amount` o `rut` en la extensión, no llegan al diario de eventos.
+export function eventoDeCobro(env) {
+  const x = env?.extensions?.[EXT_COBRO];
+  if (!x || typeof x !== 'object' || Array.isArray(x)) return null;
+  const name = EVENTOS_COBRO[x.kind];
+  if (!name) return null;
+  if (typeof x.request_id !== 'string' || !ID_PEDIDO.test(x.request_id)) return null;
+  if (!MONEDAS.includes(x.currency)) return null;
+  return { name, data: { request_id: x.request_id, currency: x.currency } };
+}
+
+// ¿Puede esta tarjeta recibir un cobro? Devuelve la razón por la que no, o null.
+// No a la casa (libro@, postmaster@...), no a un grupo, no sin llave de cifrado, y no a una
+// dirección cuya llave guarda la casa: ahí la casa descifra, y los datos bancarios pasarían por
+// ella en claro (decisión del ítem NX-502: «un cobro a claude.nico se rechaza en el cliente»).
+export function razonParaNoCobrar(card) {
+  if (!card) return 'the recipient card could not be resolved';
+  if (card.group) return `${card.address} is a group: a payment request goes to one person`;
+  if (card.custody?.keys === 'house') return `${card.address} is an address whose key the house holds (a connected Claude): the house would read the bank details. Send the request to ${card.delegation?.by || 'its owner'} instead`;
+  if (!card.enc) return `${card.address} publishes no encryption key: a payment request only travels encrypted`;
+  return null;
+}