---
name: proceso-ddia-fundamentos
description: >
  Conceptos fundamentales del libro "Designing Data-Intensive Applications" de
  Martin Kleppmann aplicables a sistemas no-distribuidos (como SWL): Cap 1
  Reliability/Scalability/Maintainability como framework de evaluación, Cap 4
  Schema Evolution con backward/forward compatibility, Cap 12 End-to-End
  Argument y Trust-but-Verify. Cargar al diseñar manifiestos versionados,
  evaluar arquitectura de un módulo, decidir dónde validar correctitud.
when_to_use: >
  Usar cuando el usuario menciona schema versioning, backward/forward compat,
  end-to-end verification, trust but verify, reliability scalability
  maintainability, RSM framework, Operability Simplicity Evolvability,
  schema-evolution, evaluar arquitectura, decidir dónde validar.
---

# DDIA Fundamentos — RSM, Schema Evolution, End-to-End

Adaptado de Martin Kleppmann, *"Designing Data-Intensive Applications"*
(O'Reilly, 2017). Skill cubre los tres ejes del libro que aplican a SWL:

- **Capítulo 1** — Reliability, Scalability, Maintainability como framework.
- **Capítulo 4** — Schema Evolution (back/forward compatibility).
- **Capítulo 12** — End-to-End Argument + Trust-but-Verify.

Los demás capítulos del libro (2-3 data models / storage, 5-10 distributed
systems) tratan dominios que SWL no es (no es BD, no es sistema distribuido).
Se descartan por filtro de dominio (regla `arquitectura.md`).

## Cuándo cargar

- Diseñar un schema nuevo (manifest, frontmatter, JSON Schema) que
  evolucionará en el tiempo.
- Auditar un módulo SWL para evaluar Reliability/Scalability/Maintainability.
- Decidir dónde poner una validación: en cada capa o solo end-to-end.
- Resolver una duda sobre "¿esto se rompe si actualizo el sistema?" — es
  pregunta de schema compatibility.

## Cuándo NO cargar

- Discusiones sobre replication, partitioning, consenso (Paxos/Raft) — esos
  capítulos DDIA no aplican a SWL.
- Streaming/event sourcing avanzado — cargar `Skill("proceso-ddia-streaming")`.
- Optimización puntual de query SQL — cargar `Skill("performance-baseline")`.

---

## Parte 1 — Reliability, Scalability, Maintainability (RSM)

Cita textual del libro (DDIA p.18, línea 1411-1453):

> "It is well known that the majority of the cost of software is not in its
> initial development, but in its ongoing maintenance — fixing bugs, keeping
> its systems operational, investigating failures, adapting it to new
> platforms, modifying it for new use cases, repaying technical debt, and
> adding new features."

### Las 3 dimensiones del RSM

**Reliability** — el sistema sigue funcionando correctamente bajo:
- Hardware faults
- Software errors
- Human errors

Tipos de respuesta:
- **Fault-tolerant**: el sistema absorbe la falla sin propagarla.
- **Resilient**: degrada con gracia, no en cascada.

**Aplicación a SWL**: hooks bloqueantes (`calidad-pre-commit`,
`escaneo-secretos`) son fault-tolerance. Las escrituras atómicas
(`hooks/lib/atomic-write.js`) son resilience contra crashes durante write.

**Scalability** — cómo cambia el rendimiento cuando crece la carga:
- Describir **carga** (parámetros: throughput, concurrent users, etc.)
- Describir **rendimiento** (latencia: p50, p95, p99)

**Aplicación a SWL**: las métricas `Skill("performance-baseline")` siguen
este modelo. Carga = sesiones concurrentes, archivos por proyecto, agentes
en cadena. Rendimiento = latencia de hooks, tiempo de respuesta de
validadores.

**Maintainability** — tres principios de diseño del libro:

> "Operability: Make it easy for operations teams to keep the system running
> smoothly.
> Simplicity: Make it easy for new engineers to understand the system, by
> removing as much complexity as possible from the system. (Note this is
> not the same as simplicity of the user interface.)
> Evolvability: Make it easy for engineers to make changes to the system in
> the future, adapting it for unanticipated use cases as requirements
> change. Also known as extensibility, modifiability, or plasticity."
> (DDIA p.18-19, líneas 1435-1449)

**Aplicación a SWL**:

| Principio DDIA | Implementación SWL |
|---|---|
| Operability | `/swl:salud`, `/swl:dashboard`, `/swl:doctor`, runbooks |
| Simplicity | Skills ≤300 líneas, módulos profundos (Ousterhout), zero-deps en `hooks/lib/` |
| Evolvability | ADRs versionados, schemas opcionales aditivos, fragments compartidos |

### Cómo usar RSM como rúbrica de evaluación

Antes de declarar un módulo "listo", pregúntate:

1. **Reliability**: ¿qué pasa si una entrada inesperada llega? ¿Si un hook
   externo falla? ¿Si el filesystem se llena?
2. **Scalability**: ¿el módulo escala con el tamaño del proyecto del
   usuario? Si tiene 1000 archivos vs 10, ¿degrada linealmente o se
   cuadratiza?
3. **Maintainability** (los 3 sub-principios):
   - ¿Un operario nuevo puede operarlo sin leer todo el código?
   - ¿Un ingeniero nuevo puede entenderlo sin un curso?
   - ¿Un cambio de requisito se acomoda sin reescribir?

Si la respuesta es "no" a más de uno, el módulo necesita refactor antes de
release.

---

## Parte 2 — Schema Evolution (Cap 4)

Cita textual del libro (DDIA p.112, línea 5706-5719):

> "Backward compatibility — Newer code can read data that was written by
> older code.
>
> Forward compatibility — Older code can read data that was written by
> newer code.
>
> Backward compatibility is normally not hard to achieve: as author of the
> newer code, you know the format of data written by older code, and so
> you can explicitly handle it (if necessary by simply keeping the old code
> to read the old data). Forward compatibility can be trickier, because it
> requires older code to ignore additions made by a newer version of the
> code."

### Las 2 direcciones de compatibilidad

Cuando un schema evoluciona, hay dos preguntas distintas:

| Pregunta | Tipo | Difficulty |
|---|---|---|
| ¿Código nuevo lee datos viejos? | Backward | Fácil |
| ¿Código viejo lee datos nuevos? | Forward | Más difícil |

**Backward compat es fácil**: el código nuevo conoce ambas versiones del
schema, puede manejar los dos formatos.

**Forward compat es difícil**: el código viejo NO sabe que existe el campo
nuevo. Para que funcione, el código viejo debe **ignorar campos
desconocidos** sin romperse.

### Aplicación a schemas SWL

SWL tiene 14 archivos `schemas/*.schema.json`. Reglas operativas:

1. **Campos nuevos siempre opcionales**: agregar `myField: { type: "..." }`
   sin marcarlo `required`. Código viejo lo ignora (forward-compat OK).
   Código nuevo lo usa si está presente (backward-compat OK).

2. **NUNCA renombrar campos en MINOR/PATCH**: rename = breaking. Si hay
   que renombrar, mantener ambos durante 1 release (deprecación) y
   eliminar en el MAJOR siguiente.

3. **NUNCA cambiar tipo de un campo en MINOR/PATCH**: cambiar `string` →
   `array` rompe ambas direcciones. Es MAJOR.

4. **Agregar enum value es compatible**: si `nivelRiesgo` acepta
   `[BAJO, MEDIO, ALTO]`, agregar `CRÍTICO` es backward-compat (código
   nuevo lo entiende, código viejo lo rechaza pero no se rompe).

5. **Eliminar enum value es breaking**: código nuevo rechaza algo que
   código viejo escribía.

### Detección de breaking changes

Helper `scripts/lib/schema-version.js` (creado en F4) implementa estas
reglas. Uso esperado:

```js
const { verificarCompatibilidad } = require('./scripts/lib/schema-version');
const r = verificarCompatibilidad(documento, schema);
// r = { compatible: bool, modo: "backward"|"forward"|"none", advertencias }
```

Tres modos según versiones:
- Doc 1.0.0 + Schema 1.0.0 → `modo: "none"` (idénticas).
- Doc 1.0.0 + Schema 1.1.0 → `modo: "forward"` (dato viejo, código nuevo).
- Doc 1.1.0 + Schema 1.0.0 → `modo: "backward"` (dato nuevo, código viejo).
- Doc 2.0.0 + Schema 1.0.0 → `compatible: false` (MAJOR rompe).

---

## Parte 3 — End-to-End Argument (Cap 12)

Concepto del libro: la verificación de correctitud debe vivir en la
frontera del sistema (end-to-end), no en cada capa intermedia.

> "The End-to-End Argument for Databases" (DDIA p.516, sección referenciada)

### El principio aplicado

Si validas en cada capa intermedia:
- Capa 1: valida → pasa
- Capa 2: valida → pasa
- Capa 3: valida → pasa
- Resultado: dato corrupto entregado al usuario porque ninguna capa
  verificó la **invariante de negocio** completa.

Si validas end-to-end:
- Capa 1, 2, 3: hacen su trabajo sin validar
- Frontera del sistema: verifica la invariante completa
- Resultado: si falla, se detecta antes de entregar al usuario.

### Aplicación a SWL

- `/swl:verificar` con goal-backward 4 niveles es end-to-end.
- Hooks de validación intermedios (`calidad-pre-commit`,
  `escaneo-secretos`) son fault-tolerance, no end-to-end. Detectan
  problemas obvios temprano para reducir blast radius — no reemplazan la
  verificación end-to-end.
- Las dos capas son complementarias: hooks rápidos en cada step, verifier
  end-to-end al cierre de fase.

### Trust-but-Verify (Cap 12, p.528)

El sistema debe **confiar provisionalmente** en sus componentes
(hooks pasan → asumimos correcto) pero **verificar** la invariante final
con evidencia, no con auto-reporte de los componentes.

Aplicación SWL: regla `verificar-citas-normativas.md` aplica este
principio a citas archivo:línea — un sub-agente reportó "está
implementado en X:42"; el padre verifica con `Read`+`grep` antes de
aceptar.

---

## Resumen — qué se llevó SWL del libro

| Concepto DDIA | Dónde vive en SWL |
|---|---|
| Reliability/Scalability/Maintainability como framework | Este skill como rúbrica de evaluación |
| Operability / Simplicity / Evolvability | Skills ≤300 líneas + observabilidad-swl + ADRs |
| Backward / Forward compat | `$schemaVersion` + `scripts/lib/schema-version.js` (F4) |
| End-to-End Argument | `/swl:verificar` goal-backward |
| Trust-but-Verify | regla `verificar-citas-normativas.md` |

## Origen

Skill creado el 2026-05-18 como parte de Opción B de integración
`temp/Designing Data Intensive Applications by Martin Kleppmann.md`. Ver
ADR-0025 para la decisión de scope. Skill hermano:
`proceso-ddia-streaming` (Cap 11 event sourcing aplicado a
`evolucion/*.jsonl`).
