@nyx5/nyx5 0.1.0

package/src/libro/libro.js

@@ -0,0 +1,250 @@
+// Nyx5/1 — Libro: el ledger de doble entrada de una casa (dominio).
+//
+// El Libro es el segundo componente del sistema; el primero es el Correo. No tiene login propio:
+// toda operación llega como un sobre firmado a `libro@<dominio>`, y la identidad del remitente ya
+// viene verificada por la cadena de confianza del Correo. El Libro solo decide si la operación es
+// válida (partes, estado, saldo) y ejecuta el asiento.
+//
+// Kernel: siete primitivas y nada más. Los contratos (contratos.js) se componen encima.
+//   1. cotizar   -> no toca el libro: es un documento firmado por el vendedor (verifyQuote lo valida)
+//   2. cobrar    -> transfer(de, a, monto)  con reparto de fee a la casa
+//   3. retener   -> hold(de, escrow, monto)
+//   4. liberar   -> release(escrow, a, monto) con fee
+//   5. devolver  -> refund(escrow, a, monto) sin fee
+//   6. repartir  -> post() con N líneas que suman cero (el fee de la casa es un reparto)
+//   7. afianzar  -> hold() con condición de salida distinta (forfeit / release)
+// Transversales: idempotencia (por id de sobre) y meta (contexto legible por máquina en cada asiento).
+//
+// Cuentas: `agente@dominio` (cualquier agente verificable, de esta casa o de otra), `casa@<dominio>`
+// (la distribuidora: emite tokens, cobra fees; es la única que puede quedar en negativo) y
+// `escrow:<contrato>` (fondos retenidos). Un asiento es una lista de líneas {cuenta, delta} que suman 0.
+//
+// ESCRITURAS: cada operación acumula sus escrituras en una transacción (this.tx) y el llamador la
+// sella con commit() -> store.libroCommit(bundle). En FileStore el commit es secuencial (proceso
+// único); en D1 es un batch atómico donde el número de asiento y el id de la op son claves únicas:
+// dos operaciones concurrentes no pueden duplicar un asiento ni descuadrar los saldos — la segunda
+// falla cerrado y el correo la reintenta.
+
+import { signObject, verifyObject, canonical, sha256hex, uuid } from '../nucleo/crypto.js';
+import { Resolver, parseAddress } from '../correo/resolver.js';
+import { CONTRATOS } from './contratos.js';
+import { LibroError } from './errores.js';
+export { LibroError };
+
+export const MEDIA = {
+  op: 'application/nyx5.libro+json',
+  cotizacion: 'application/nyx5.cotizacion+json',
+  recibo: 'application/nyx5.recibo+json',
+};
+
+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 = () => {} }) {
+    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.casa = `casa@${domain}`;
+    this.address = `libro@${domain}`;
+    this.tx = null; // transacción en curso: { state, asientos, contracts: Map, mandates: Map, op }
+    this._lock = Promise.resolve(); // serializa las transacciones DENTRO de esta instancia; entre
+                                    // procesos/isolates protegen las constraints de D1 (fallar cerrado)
+  }
+  _serial(fn) { const run = this._lock.then(fn); this._lock = run.catch(() => {}); return run; }
+  get feePct() { return this.feeBps / 10_000; } // compat de lectura (tarjeta de libro@)
+
+  // ---------- transacción ----------
+  // El estado se lee UNA vez al abrir y no se vuelve a leer: si otra operación comete mientras
+  // esta decide, el número de asiento que ésta reservó ya estará tomado y su commit falla cerrado.
+  // Releer aquí sería el bug: dos cobros que leyeron el mismo mandato tomarían números distintos
+  // 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 };
+  }
+  _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 };
+  }
+  async _commit() {
+    const t = this.tx;
+    // Una operación que muta el Libro sin mover dinero (revocar, entregar, sub-delegar) también
+    // consume su número de asiento: es la única forma de que choque con quien corre en paralelo.
+    // El asiento de control tiene lines vacío, así que sigue cuadrando en cero y queda auditable.
+    if (!t.asientos.length && (t.contracts.size || t.mandates.size)) {
+      const st = t.state ?? t.base;
+      t.asientos.push(signObject({ id: uuid(), n: st.seq + 1, at: iso(), house: this.domain, concept: t.concepto, lines: [], meta: { kind: 'control' }, refs: t.refs }, this.keys));
+      t.state = { seq: st.seq + 1, balances: st.balances };
+    }
+    const b = this._bundle();
+    this.tx = null;
+    await this.store.libroCommit(b);
+    return b;
+  }
+  _abort() { this.tx = null; }
+  // Lecturas que ven las escrituras pendientes de la propia transacción:
+  async _state() { return this.tx ? (this.tx.state ?? this.tx.base) : await this.store.libroState(); }
+  async getContract(id) { return this.tx?.contracts.get(id) ?? await this.store.libroGetContract(id); }
+  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); }
+
+  // ---------- consultas ----------
+  get ops() { return Object.keys(CONTRATOS.ops); }
+  async balance(account) { return (await this.store.libroState()).balances[account] || 0; }
+  fee(amount) { return Math.floor((amount * this.feeBps) / 10_000); }
+  async account(address) {
+    const contracts = (await this.store.libroListContracts()).filter((c) => [c.seller, c.buyer, c.verifier, c.arbiter].includes(address));
+    const mandates = (await this.store.libroListMandates()).filter((m) => m.grantor === address || m.grantee === address);
+    return { account: address, balance: await this.balance(address), contracts, mandates };
+  }
+  async journal() { return this.store.libroJournal(); }
+
+  // ---------- el kernel: un asiento ----------
+  // lines: [{ account, delta }]; suma cero; nadie salvo la casa queda negativo.
+  async post(concept, lines, meta = {}, refs = {}) {
+    const total = lines.reduce((s, l) => s + l.delta, 0);
+    if (total !== 0) throw new LibroError(500, `asiento descuadrado (${total})`);
+    for (const l of lines) if (!Number.isInteger(l.delta)) throw new LibroError(400, 'los montos son enteros (tokens)');
+    const state = await this._state();
+    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})`);
+    }
+    const asiento = signObject({ id: uuid(), n: state.seq + 1, at: iso(), house: this.domain, concept, lines, meta, refs }, this.keys);
+    if (this.tx) {
+      this.tx.asientos.push(asiento);
+      this.tx.state = { seq: state.seq + 1, balances: next };
+    } else {
+      // asiento suelto (topup administrativo): transacción propia, con el mismo candado
+      await this.store.libroCommit({ base: state, state: { seq: state.seq + 1, balances: next }, asientos: [asiento], contracts: [], mandates: [], op: null });
+    }
+    return asiento;
+  }
+
+  // Primitivas construidas sobre post()
+  async topup(account, amount, concept = 'carga', meta = {}) {
+    parseAddress(account); this._amount(amount);
+    const asentar = () => this.post(concept, [{ account: this.casa, delta: -amount }, { account, delta: amount }], { kind: 'topup', ...meta });
+    return this.tx ? asentar() : this._serial(asentar);
+  }
+  // referrer opcional { address, share (bps) }: la comisión sale del monto (la recibe el vendedor),
+  // no se suma al precio. El asiento pasa a 4 líneas y sigue cuadrando en cero.
+  async transfer(from, to, amount, concept, meta = {}, refs = {}, referrer = null) {
+    this._amount(amount);
+    const fee = this.fee(amount);
+    const com = referrer ? Math.floor((amount * referrer.share) / 10_000) : 0;
+    const lines = [{ account: from, delta: -amount }, { account: to, delta: amount - fee - com }];
+    if (fee) lines.push({ account: this.casa, delta: fee });
+    if (com) lines.push({ account: referrer.address, delta: com });
+    return this.post(concept, lines, { kind: 'charge', fee, ...(com ? { referrer: referrer.address, commission: com } : {}), ...meta }, refs);
+  }
+  async hold(from, contractId, amount, concept, meta = {}, refs = {}) {
+    this._amount(amount);
+    return this.post(concept, [{ account: from, delta: -amount }, { account: `escrow:${contractId}`, delta: amount }], { kind: 'hold', ...meta }, refs);
+  }
+  async release(contractId, to, amount, concept, meta = {}, refs = {}, referrer = null) {
+    this._amount(amount);
+    const fee = this.fee(amount);
+    const com = referrer ? Math.floor((amount * referrer.share) / 10_000) : 0;
+    const lines = [{ account: `escrow:${contractId}`, delta: -amount }, { account: to, delta: amount - fee - com }];
+    if (fee) lines.push({ account: this.casa, delta: fee });
+    if (com) lines.push({ account: referrer.address, delta: com });
+    return this.post(concept, lines, { kind: 'release', fee, ...(com ? { referrer: referrer.address, commission: com } : {}), ...meta }, refs);
+  }
+  async refund(contractId, to, amount, concept, meta = {}, refs = {}) {
+    this._amount(amount);
+    return this.post(concept, [{ account: `escrow:${contractId}`, delta: -amount }, { account: to, delta: amount }], { kind: 'refund', ...meta }, refs);
+  }
+  _amount(a) { if (!Number.isInteger(a) || a <= 0) throw new LibroError(400, `monto inválido: ${a}`); }
+
+  // ---------- 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) {
+    if (!CONTRATOS[contract]?.quoteable) throw new LibroError(400, `contrato no cotizable: ${contract}`);
+    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:
+    // el comprador paga igual y la casa cobra igual. verifyQuote valida los límites al aceptar.
+    if (referrer != null) {
+      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);
+  }
+  async verifyQuote(q, buyer) {
+    if (q?.tipo !== 'cotizacion' || !q.id || !q.seller || !q.signature) throw new LibroError(400, 'cotización malformada');
+    // Solo tipos cotizables: una cotización firmada a mano con un kind inexistente (o no cotizable)
+    // se rechaza limpio aquí, no explota en onAccept.
+    if (!CONTRATOS[q.contract]?.quoteable) throw new LibroError(400, `contrato no cotizable: ${q.contract}`);
+    if (q.house !== this.domain) throw new LibroError(400, `la cotización es para la casa ${q.house}, no ${this.domain}`);
+    if (q.buyer !== buyer) throw new LibroError(403, 'la cotización no está dirigida a quien la acepta');
+    if (q.expires && Date.parse(q.expires) < Date.now()) throw new LibroError(410, 'cotización vencida');
+    if (q.arbiter) { try { parseAddress(q.arbiter); } catch { throw new LibroError(400, 'árbitro inválido en la cotización'); } }
+    if (q.referrer != null) {
+      try { parseAddress(q.referrer.address); } catch { throw new LibroError(400, 'referidor inválido en la cotización'); }
+      if (!Number.isInteger(q.referrer.share) || q.referrer.share <= 0) throw new LibroError(400, 'referrer.share debe ser un entero de basis points > 0');
+      // El fee de la casa y la comisión salen ambos del monto: juntos no pueden dejar al vendedor en negativo.
+      if (this.feeBps + q.referrer.share > 10_000) throw new LibroError(400, `fee (${this.feeBps} bps) + comisión (${q.referrer.share} bps) supera el 100% del precio`);
+      if (q.referrer.address === q.seller) throw new LibroError(400, 'el vendedor no puede ser su propio referidor');
+    }
+    this._amount(q.price);
+    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');
+    if (await this.store.libroFindContractByQuote(q.id)) throw new LibroError(409, 'cotización ya aceptada');
+    return card;
+  }
+
+  // ---------- entrada: un sobre dirigido a libro@<dominio> ----------
+  // Devuelve { ok, code, reason, result, recibos: [{ to: [...], body }] }. Idempotente por id de sobre.
+  async handle(env, senderCard) {
+    const prev = await this.store.libroGetOp(env.id);
+    if (prev) return { ...prev, duplicate: true };
+    if (!env.content || env.content.media !== MEDIA.op) return { ok: false, code: 400, reason: `el Libro solo acepta content.media = ${MEDIA.op} (sin cifrar: la casa debe leerlo)` };
+    const body = env.content.body || {};
+    const op = CONTRATOS.ops[body.op];
+    if (!op) return { ok: false, code: 400, reason: `operación desconocida: ${body.op}. Válidas: ${Object.keys(CONTRATOS.ops).join(', ')}` };
+    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 });
+      let result;
+      try { result = await op(ctx); }
+      catch (e) {
+        this._abort();
+        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 || [] };
+      this.tx.op = { id: env.id, result: out };
+      try { await this._commit(); }
+      catch (e) {
+        // Conflicto de concurrencia (asiento u op duplicados en D1): la op ya corrió en paralelo.
+        const cached = await this.store.libroGetOp(env.id);
+        if (cached) return { ...cached, duplicate: true };
+        throw e;
+      }
+      return out;
+    });
+  }
+
+  // Estampilla: un sobre con `stamp` hacia un buzón con política `stamp` paga al llegar.
+  // NO comete: devuelve { asiento, bundle } para que la estafeta lo selle JUNTO con el buzón y el
+  // 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})`);
+    return this._serial(async () => {
+    await this._begin('estampilla', { envelope: env.id });
+    try {
+      const asiento = await this.transfer(env.from, recipient, s.amount, `estampilla ${env.from} -> ${recipient}`, { kind: 'stamp' }, { envelope: env.id, envelope_sha256: sha256hex(canonical(env)) });
+      const bundle = this._bundle();
+      this.tx = null;
+      return { asiento, bundle };
+    } catch (e) { this._abort(); throw e; }
+    });
+  }
+}

package/src/nucleo/almacen-d1.js

@@ -0,0 +1,223 @@
+// Nyx5/1 — D1Store: la misma interfaz que FileStore, sobre Cloudflare D1 (o el emulador
+// d1-local.js en tests). Async real, y la atomicidad que FileStore le debe al proceso único
+// aquí la dan las transacciones (db.batch) y las constraints del esquema (0002_nyx5.sql):
+//   - un asiento concurrente con el mismo n -> el batch entero falla cerrado (PK diario.n)
+//   - una op reentregada -> INSERT choca con PK ops.id y el Libro responde el resultado cacheado
+//   - una cotización re-aceptada -> UNIQUE contratos.quote_id
+// Los documentos se guardan como JSON íntegro (columna doc): los campos desconocidos sobreviven
+// el roundtrip y las firmas siguen verificando (invariante 7).
+
+import { LibroError } from '../libro/errores.js';
+
+const j = (v) => JSON.stringify(v);
+const p = (row, col = 'doc') => (row ? JSON.parse(row[col]) : null);
+const iso = () => new Date().toISOString();
+
+export class D1Store {
+  constructor(db) { this.db = db; }
+
+  // --- dominio ---
+  async getDomain() { return p(await this.db.prepare('SELECT doc FROM nyx5_domain WHERE id = 1').first()); }
+  async putDomain(v) { await this.db.prepare('INSERT INTO nyx5_domain (id, doc) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc').bind(j(v)).run(); }
+  async putDomainIfAbsent(v) {
+    const r = await this.db.prepare('INSERT OR IGNORE INTO nyx5_domain (id, doc) VALUES (1, ?)').bind(j(v)).run();
+    return r.meta.changes === 1;
+  }
+
+  // --- agentes ---
+  async getAgent(local) { return p(await this.db.prepare('SELECT doc FROM nyx5_agents WHERE local = ?').bind(local).first()); }
+  async putAgent(local, v) { await this.db.prepare('INSERT INTO nyx5_agents (local, doc, updated) VALUES (?, ?, ?) ON CONFLICT(local) DO UPDATE SET doc = excluded.doc, updated = excluded.updated').bind(local, j(v), iso()).run(); }
+  // Alta atómica: true si este llamador creó el nombre. Dos altas concurrentes del mismo nombre
+  // ya no se pisan la clave (ni duplican el regalo de bienvenida).
+  async putAgentIfAbsent(local, v) {
+    const r = await this.db.prepare('INSERT OR IGNORE INTO nyx5_agents (local, doc, updated) VALUES (?, ?, ?)').bind(local, j(v), iso()).run();
+    return r.meta.changes === 1;
+  }
+  async listAgents() { return (await this.db.prepare('SELECT local FROM nyx5_agents ORDER BY local').all()).results.map((r) => r.local); }
+
+  // --- invitaciones ---
+  async getInvite(code) { return p(await this.db.prepare('SELECT doc FROM nyx5_invitations WHERE code = ?').bind(code).first()); }
+  async putInvite(inv) { await this.db.prepare('INSERT INTO nyx5_invitations (code, doc) VALUES (?, ?) ON CONFLICT(code) DO UPDATE SET doc = excluded.doc').bind(inv.code, j(inv)).run(); }
+  async listInvites() { return (await this.db.prepare('SELECT doc FROM nyx5_invitations').all()).results.map((r) => JSON.parse(r.doc)); }
+  // Consumo atómico de un uso: la condición viaja EN el UPDATE, así que diez canjes en paralelo
+  // de una invitación de un uso dejan pasar exactamente uno.
+  async consumeInvite(code, atIso) {
+    const r = await this.db.prepare(`
+      UPDATE nyx5_invitations
+      SET doc = json_set(json_set(doc, '$.used', json_extract(doc, '$.used') + 1), '$.last_used', ?)
+      WHERE code = ? AND json_extract(doc, '$.used') < json_extract(doc, '$.uses')`).bind(atIso, code).run();
+    if (r.meta.changes !== 1) return null;
+    return this.getInvite(code);
+  }
+
+  // --- deduplicación ---
+  async getSeen(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_seen WHERE id = ?').bind(id).first()); }
+  async putSeen(id, rec) { await this.db.prepare('INSERT INTO nyx5_seen (id, doc) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc').bind(id, j({ id, at: iso(), ...rec })).run(); }
+  async markSeenIfNew(id, meta = {}) {
+    const r = await this.db.prepare('INSERT OR IGNORE INTO nyx5_seen (id, doc) VALUES (?, ?)').bind(id, j({ id, at: iso(), ...meta })).run();
+    return r.meta.changes === 1;
+  }
+
+  // --- buzones ---
+  async putMail(local, envelope, meta = {}) {
+    const received = iso();
+    await this.db.prepare('INSERT INTO nyx5_mailbox (local, id, doc, received) VALUES (?, ?, ?, ?) ON CONFLICT(local, id) DO NOTHING')
+      .bind(local, envelope.id, j({ ...meta, received, envelope }), received).run();
+  }
+  async listMail(local) {
+    return (await this.db.prepare('SELECT doc FROM nyx5_mailbox WHERE local = ? AND acked IS NULL ORDER BY received, id').bind(local).all()).results.map((r) => JSON.parse(r.doc));
+  }
+  async ackMail(local, id) {
+    const r = await this.db.prepare('UPDATE nyx5_mailbox SET acked = ? WHERE local = ? AND id = ? AND acked IS NULL').bind(iso(), local, id).run();
+    return r.meta.changes === 1;
+  }
+
+  // --- cola de salida ---
+  _jobRow(job) { return [job.id, j(job), job.next_attempt, job.status, job.claimed_until || 0]; }
+  async enqueue(job) {
+    await this.db.prepare('INSERT INTO nyx5_queue (id, doc, next_attempt, status, claimed_until) VALUES (?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc, next_attempt = excluded.next_attempt, status = excluded.status, claimed_until = excluded.claimed_until')
+      .bind(...this._jobRow(job)).run();
+  }
+  async listQueue() { return (await this.db.prepare('SELECT doc FROM nyx5_queue').all()).results.map((r) => JSON.parse(r.doc)); }
+  async updateJob(job) { await this.enqueue(job); }
+  async removeJob(id) { await this.db.prepare('DELETE FROM nyx5_queue WHERE id = ?').bind(id).run(); }
+  async claimDueJobs(nowMs, max = 20) {
+    const nowIso = new Date(nowMs).toISOString();
+    const until = nowMs + 60_000;
+    // Reclamo atómico: un solo UPDATE marca y devuelve; dos ticks concurrentes no comparten trabajo.
+    const r = await this.db.prepare(`
+      UPDATE nyx5_queue SET status = 'inflight', claimed_until = ?
+      WHERE id IN (
+        SELECT id FROM nyx5_queue
+        WHERE next_attempt <= ? AND (status IN ('queued','retrying') OR (status = 'inflight' AND claimed_until < ?))
+        LIMIT ?
+      ) RETURNING doc`).bind(until, nowIso, nowMs, max).all();
+    return r.results.map((row) => { const job = JSON.parse(row.doc); job.status = 'inflight'; job.claimed_until = until; return job; });
+  }
+
+  // --- outbox ---
+  async putOutbox(local, entry) {
+    await this.db.prepare('INSERT INTO nyx5_outbox (local, job, doc) VALUES (?, ?, ?) ON CONFLICT(local, job) DO UPDATE SET doc = excluded.doc').bind(local, entry.job, j(entry)).run();
+  }
+  async listOutbox(local) { return (await this.db.prepare('SELECT doc FROM nyx5_outbox WHERE local = ?').bind(local).all()).results.map((r) => JSON.parse(r.doc)); }
+
+  // --- nonces ---
+  async useNonce(key, tsMs) {
+    const r = await this.db.prepare('INSERT OR IGNORE INTO nyx5_nonces (key, ts) VALUES (?, ?)').bind(key, tsMs).run();
+    return r.meta.changes === 1;
+  }
+  async pruneNonces(beforeMs) { await this.db.prepare('DELETE FROM nyx5_nonces WHERE ts < ?').bind(beforeMs).run(); }
+
+  // --- pins (una fila por dominio: el primero gana y ningún isolate pisa lo que otro aprendió) ---
+  async getPins() {
+    const r = await this.db.prepare('SELECT domain, kid FROM nyx5_pin').all();
+    return Object.fromEntries(r.results.map((x) => [x.domain, x.kid]));
+  }
+  async putPin(domain, kid) {
+    const r = await this.db.prepare('INSERT OR IGNORE INTO nyx5_pin (domain, kid, at) VALUES (?, ?, ?)').bind(domain, kid, iso()).run();
+    return r.meta.changes === 1;
+  }
+  // Compat: recibe el mapa completo pero NUNCA borra; cada pin se agrega si no existía.
+  async putPins(v) { for (const [d, k] of Object.entries(v || {})) await this.putPin(d, k); }
+
+  // ===== Libro =====
+  async libroState() {
+    const row = await this.db.prepare('SELECT seq, balances FROM nyx5_libro_state WHERE id = 1').first();
+    return row ? { seq: row.seq, balances: JSON.parse(row.balances) } : { seq: 0, balances: {} };
+  }
+  async libroPutState(v) { await this.db.prepare('UPDATE nyx5_libro_state SET seq = ?, balances = ? WHERE id = 1').bind(v.seq, j(v.balances)).run(); }
+  async libroAppend(asiento) { await this.db.batch(this._asientoStmts(asiento)); }
+  _asientoStmts(asiento) {
+    return [
+      this.db.prepare('INSERT INTO nyx5_libro_diario (n, id, doc) VALUES (?, ?, ?)').bind(asiento.n, asiento.id, j(asiento)),
+      ...asiento.lines.map((l) => this.db.prepare('INSERT INTO nyx5_libro_lineas (n, account, delta) VALUES (?, ?, ?)').bind(asiento.n, l.account, l.delta)),
+    ];
+  }
+  async libroJournal() { return (await this.db.prepare('SELECT doc FROM nyx5_libro_diario ORDER BY n').all()).results.map((r) => JSON.parse(r.doc)); }
+  async libroGetContract(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_contratos WHERE id = ?').bind(id).first()); }
+  _contractStmt(c) {
+    return this.db.prepare('INSERT INTO nyx5_libro_contratos (id, quote_id, doc) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc, quote_id = excluded.quote_id').bind(c.id, c.quote_id || null, j(c));
+  }
+  async libroPutContract(c) { await this._contractStmt(c).run(); }
+  async libroListContracts() { return (await this.db.prepare('SELECT doc FROM nyx5_libro_contratos').all()).results.map((r) => JSON.parse(r.doc)); }
+  async libroFindContractByQuote(quoteId) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_contratos WHERE quote_id = ?').bind(quoteId).first()); }
+  async libroGetMandate(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_mandatos WHERE id = ?').bind(id).first()); }
+  _mandateStmt(m) { return this.db.prepare('INSERT INTO nyx5_libro_mandatos (id, doc) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc').bind(m.id, j(m)); }
+  async libroPutMandate(m) { await this._mandateStmt(m).run(); }
+  async libroListMandates() { return (await this.db.prepare('SELECT doc FROM nyx5_libro_mandatos').all()).results.map((r) => JSON.parse(r.doc)); }
+  async libroGetOp(id) { return p(await this.db.prepare('SELECT doc FROM nyx5_libro_ops WHERE id = ?').bind(id).first()); }
+  async libroPutOp(id, v) { await this.db.prepare('INSERT INTO nyx5_libro_ops (id, doc) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc').bind(id, j(v)).run(); }
+  async libroStatement(account, limit) {
+    const r = await this.db.prepare(`
+      SELECT doc FROM nyx5_libro_diario WHERE n IN (SELECT DISTINCT n FROM nyx5_libro_lineas WHERE account = ?)
+      ORDER BY n DESC LIMIT ?`).bind(account, limit).all();
+    return r.results.map((row) => JSON.parse(row.doc)).reverse();
+  }
+
+  // Un movimiento del Libro, atómico. El orden importa: el diario va primero (PK n = candado
+  // optimista del ledger entero) para que un conflicto aborte el batch antes de tocar nada más.
+  _libroCommitStmts(bundle) {
+    const stmts = [];
+    for (const a of bundle.asientos || []) stmts.push(...this._asientoStmts(a));
+    if (bundle.state) stmts.push(this.db.prepare('UPDATE nyx5_libro_state SET seq = ?, balances = ? WHERE id = 1').bind(bundle.state.seq, j(bundle.state.balances)));
+    for (const c of bundle.contracts || []) stmts.push(this._contractStmt(c));
+    for (const m of bundle.mandates || []) stmts.push(this._mandateStmt(m));
+    if (bundle.op) stmts.push(this.db.prepare('INSERT INTO nyx5_libro_ops (id, doc) VALUES (?, ?)').bind(bundle.op.id, j(bundle.op.result)));
+    return stmts;
+  }
+  async libroCommit(bundle) {
+    const stmts = this._libroCommitStmts(bundle);
+    if (!stmts.length) return;
+    try { await this.db.batch(stmts); }
+    catch (e) { throw this._traducirConflicto(e); }
+  }
+
+  // La entrega de un sobre entera, en un batch: dedupe + buzones + estampillas.
+  async inboundCommit(bundle) {
+    const stmts = [];
+    for (const lb of bundle.libro || []) stmts.push(...this._libroCommitStmts(lb));
+    for (const m of bundle.mails || []) {
+      const received = iso();
+      stmts.push(this.db.prepare('INSERT INTO nyx5_mailbox (local, id, doc, received) VALUES (?, ?, ?, ?) ON CONFLICT(local, id) DO NOTHING')
+        .bind(m.local, m.envelope.id, j({ ...m.meta, received, envelope: m.envelope }), received));
+    }
+    if (bundle.seen) stmts.push(this.db.prepare('INSERT INTO nyx5_seen (id, doc) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET doc = excluded.doc')
+      .bind(bundle.seen.id, j({ id: bundle.seen.id, at: iso(), ...bundle.seen.rec })));
+    if (!stmts.length) return;
+    try { await this.db.batch(stmts); }
+    catch (e) { throw this._traducirConflicto(e); }
+  }
+
+  _traducirConflicto(e) {
+    // Un choque de constraint es concurrencia legítima, no un rechazo del contenido: se responde
+    // 421 (temporal, en la lista RETRYABLE de la estafeta) para que el correo lo reintente y la
+    // segunda pasada gane o vea el resultado ya cacheado. Con 409 el sobre se rebotaba como
+    // fallo permanente y la operación válida se perdía.
+    if (/UNIQUE|PRIMARY KEY|constraint/i.test(String(e?.message))) {
+      return Object.assign(new LibroError(421, `conflicto de concurrencia en el ledger, reintentable: ${e.message}`), { transient: true });
+    }
+    return e;
+  }
+
+  // ===== Índice federado =====
+  async indexGetHouse(domain) { return p(await this.db.prepare('SELECT doc FROM nyx5_indice_casas WHERE domain = ?').bind(domain).first()); }
+  async indexPutHouse(h) { await this.db.prepare('INSERT INTO nyx5_indice_casas (domain, doc) VALUES (?, ?) ON CONFLICT(domain) DO UPDATE SET doc = excluded.doc').bind(h.domain, j(h)).run(); }
+  async indexListHouses() { return (await this.db.prepare('SELECT doc FROM nyx5_indice_casas').all()).results.map((r) => JSON.parse(r.doc)); }
+  async indexReplaceAgents(domain, cards) {
+    await this.db.batch([
+      this.db.prepare('DELETE FROM nyx5_indice_agentes WHERE house = ?').bind(domain),
+      ...cards.map((c) => this.db.prepare('INSERT INTO nyx5_indice_agentes (house, address, doc) VALUES (?, ?, ?)').bind(domain, c.address, j(c))),
+    ]);
+  }
+  async indexSearch({ q, capability, accepts, house, limit = 50, offset = 0 } = {}) {
+    const where = []; const binds = [];
+    if (house) { where.push('house = ?'); binds.push(house); }
+    if (capability) { where.push("json_extract(doc, '$.capabilities.' || ?) IS NOT NULL"); binds.push(capability); }
+    if (accepts) { where.push("EXISTS (SELECT 1 FROM json_each(doc, '$.capabilities.accepts') WHERE value = ?)"); binds.push(accepts); }
+    if (q) { where.push('lower(doc) LIKE ?'); binds.push(`%${String(q).toLowerCase()}%`); }
+    const w = where.length ? `WHERE ${where.join(' AND ')}` : '';
+    const total = (await this.db.prepare(`SELECT COUNT(*) AS c FROM nyx5_indice_agentes ${w}`).bind(...binds).first()).c;
+    const rows = await this.db.prepare(`SELECT doc FROM nyx5_indice_agentes ${w} ORDER BY house, address LIMIT ? OFFSET ?`).bind(...binds, limit, offset).all();
+    return { total, offset, agents: rows.results.map((r) => JSON.parse(r.doc)) };
+  }
+}