# 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](#trabajo-opcional-eventual)
para lo que queda por tocar, si algún día hace falta.

- **89 tests** (unitarios + `proptest` + integración), `cargo clippy` limpio.
- 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 `spent` por dispositivo, e identidad como conjunto de
  dispositivos. Si el sustrato no lo da, `open` **rehú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: `sync` devuelve
  `CloneDetected` como **alarma**, no recuperación.
- **Limita** la disponibilidad bajo partición al presupuesto local; `spend`
  devuelve `Rejected { spendable }` en vez de sobregirar o colgarse.

```rust
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

```sh
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:

1. **Multi-invariante para Tawasuyu.** Si aparece la necesidad de varios contadores
   acoplados, endurecer `reach::CoupledInvariants` (el certificado del politopo) +
   `d_r` routers escalares hacia una API estable. **No** vía el Laplaciano de haces
   (colapsa al router escalar con restricciones identidad — ver `REACH.md`), salvo
   que surja un caso real de coupling en bases incompatibles.
2. **Restricciones no monótonas** (`C` con signos mixtos): el escrow no las cubre;
   es un problema abierto que necesitaría reservas de otro tipo (`REACH.md`).
3. **`diffuse` proactivo 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.