README.md
sheafsync
Motor en Rust para decidir, con demostración y no a ojo, cuándo un conjunto de réplicas local-first puede operar sin coordinación y cuándo no — y, cuando la respuesta es "sí, dentro de límites", proveer el mecanismo que lo garantiza.
Estado: CERRADO. La API de M4 (adapter::SovereignAccount) está congelada y
en producción (consumida por Tawasuyu). El resto es historia de diseño y
exploración, documentada con honestidad. Ver Trabajo opcional
para lo que queda por tocar, si algún día hace falta.
- 89 tests (unitarios +
proptest+ integración),cargo clippylimpio. - Rust edición 2021. Dependencias:
petgraph,nalgebra,thiserror,proptest(dev).
Qué es (y qué terminó siendo)
El proyecto nació como una apuesta topológica: modelar el estado distribuido como
un haz celular y usar su cohomología (H¹) para detectar obstrucciones a la
consistencia. Esa apuesta se puso a prueba honestamente y, capa tras capa, el
resultado fue humillante y valioso a la vez: la maquinaria de haces casi nunca
fue lo que sostuvo la garantía. El valor real vino de implementar bien prior-art
de sistemas (CRDTs, CALM, I-confluence, escrow / Bounded Counter) y de nombrar
con precisión las fronteras (CAP, supuestos físicos).
El registro completo de ese arco —incluyendo cada reclamo que hubo que retirar— está en los documentos de diseño. Se conserva a propósito: un cuaderno de laboratorio confiable vale más que un resultado fuerte reclamado de más.
El arco, sin adornos
| Fase | Prometía | Terminó siendo | Doc |
|---|---|---|---|
| MVP lineal (M0–M3) | detectar coordinación vía H¹ | medía topología (H¹=β₁); falso-positivo en ciclos | DESIGN.md, DISCREPANCIES.md |
| Retículos / Tarski (T5–T7) | cerrar la brecha | circular — el encoding leía la etiqueta | ADDENDUM.md, FLIPS.md |
| I-confluence (T8) | superar a CALM | detección, no evitación; punto ciego | T8.md, STRONG_RESULT.md |
| Escrow (T9) | evitación real | certificado sobre el politopo, ruteo por el grafo | T9.md, COMPARISON.md |
| Escrow dinámico (T10) | seguro en snapshot | seguro bajo concurrencia / partición / crash | T10.md, AVAILABILITY.md |
| Fuente monótona (T11) | seguro sin más | seguro módulo un supuesto físico nombrado (CAP) | T11.md, BOUNDARY.md |
| Adaptador (M4) | — | API congelada, contrato honesto, rehúsa sin durabilidad | M4.md |
| Reach multi-invariante | novedad vía haces | corrección = escrow; el haz colapsa al router escalar | REACH.md |
El terminus honesto
Seguridad coordination-free módulo un supuesto físico nombrado: cada celda de presupuesto tiene un único escritor durable. Bajo él, el certificado aplica sin coordinación. Roto (clon), el daño está acotado a una celda por clon no detectado y se detecta al reconectar — nunca silencioso ni ilimitado.
No "seguro pase lo que pase", sino "seguro salvo esta condición, y aquí está exactamente qué cuesta romperla".
La contribución real y defendible
Lo que sí queda en pie, probado:
- Evitación de coordinación por escrow, con certificado dinámico que
aguanta concurrencia, partición y crash (
escrow,durable,router). - Ruteo y localización de presupuesto por el grafo de comunicación real — el único uso legítimo del Laplaciano (el mismo que en el MVP era un detector defectuoso, reciclado como ruteador).
- Fronteras dichas, no escondidas: disponibilidad limitada bajo partición
(
AVAILABILITY.md), doble gasto por clon acotado+delatado pero no prevenible (BOUNDARY.md).
Nada de esto es novedad teórica (es O'Neil 1986 / Balegas 2015 / Bailis 2014 bien implementado); la aportación es la implementación correcta, topología-consciente y honesta sobre sus límites.
Mapa de módulos (src/)
Motor lineal (MVP, control histórico):
cell · nerve · sheaf · cohomology · verdict · oracle · linalg · gf2 · error
Pista de retículos (T5–T7, control histórico):
lattice · tarski · native
Evitación real (T8–T11, el núcleo vivo):
invariant (I-confluence + GlobalInvariant) · escrow (EscrowState, Budget,
Identity) · router (BudgetRouter) · durable (WAL) · fencing (época + clon)
Fachada en producción:
adapter (SovereignAccount — API congelada)
Experimental (no en producción):
reach (multi-invariante + Laplaciano de haces vectorial)
Contrato de M4 (lo que Tawasuyu consume)
adapter::SovereignAccount — detalle completo en M4.md:
- Requiere WAL durable de
spentpor dispositivo, e identidad como conjunto de dispositivos. Si el sustrato no lo da,openrehúsa (AdapterError) — no entrega una cuenta insegura. - Garantiza seguridad coordination-free del invariante (
value ≥ floor). - Acota y detecta (no previene) el doble gasto por clon:
syncdevuelveCloneDetectedcomo alarma, no recuperación. - Limita la disponibilidad bajo partición al presupuesto local;
spenddevuelveRejected { spendable }en vez de sobregirar o colgarse.
let cuenta = SovereignAccount::open(caps, invariante, pesos, aristas)?; // o rehúsa
match cuenta.spend(dispositivo, monto) {
SpendOutcome::Spent => { /* local o rebalanceado */ }
SpendOutcome::Rejected { spendable } => { /* fail-safe: gasta ≤ spendable */ }
}
Build y test
cargo build
cargo test # 89 tests
cargo clippy --all-targets
cargo run # demo del arco: M1 lineal → contraste Tarski → discrepancia buena
Trabajo opcional (eventual)
Nada urgente. Si algún día hace falta:
- Multi-invariante para Tawasuyu. Si aparece la necesidad de varios contadores
acoplados, endurecer
reach::CoupledInvariants(el certificado del politopo) +d_rrouters escalares hacia una API estable. No vía el Laplaciano de haces (colapsa al router escalar con restricciones identidad — verREACH.md), salvo que surja un caso real de coupling en bases incompatibles. - Restricciones no monótonas (
Ccon signos mixtos): el escrow no las cubre; es un problema abierto que necesitaría reservas de otro tipo (REACH.md). diffuseproactivo en producción: el ruteo que mitiga (no elimina) el límite de disponibilidad bajo partición existe y está probado (router), pero no está cableado en el ciclo de vida del adaptador. Es rendimiento, no corrección.
Cada uno está descrito con su frontera honesta en el doc citado. Ninguno cambia el terminus: la garantía es la que es, con los límites nombrados.