README: cierre del proyecto
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>
This commit is contained in:
Sergio
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
9de0cc601f
commit
939f9e1903
@@ -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.
|
||||
Reference in New Issue
Block a user