tawasuyu/hifas

README.md como puerta de entrada y cierre: qué es sheafsync, el arco honesto
(cada fase, qué prometía vs qué terminó siendo, con puntero al doc), el terminus
(seguridad coord-free módulo un supuesto físico nombrado), la contribución real
y defendible, el mapa de módulos (motor lineal / retículos como control
histórico; escrow como núcleo vivo; adapter en producción; reach experimental),
el contrato de M4 que Tawasuyu consume, build/test, y el trabajo opcional
eventual con su frontera honesta.

Proyecto marcado CERRADO. M4 congelado y en producción; el resto documentado.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..39b71ce
--- /dev/null
+++ b/README.md
@@ -0,0 +1,145 @@
+# 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.