1# modules/yachay/ — Notebooks computacionales reproducibles
2
3**Propósito.** Notebooks donde la reproducibilidad es verificable, no
4prometida. Un notebook es a la vez una secuencia de celdas (orden de
5lectura) y un DAG de dependencias (orden de ejecución). Un digest Merkle
6certifica que dos corridas del mismo notebook producen lo mismo.
7
8## Crates
9
10| crate         | tipo | rol                                                          |
11| ------------- | ---- | ------------------------------------------------------------ |
12| `yachay-core` | lib  | `Cell` (markdown/código/embed), `Notebook` (DAG, staleness, digest) |
13
14App: `apps/yachay` — demo CLI (`cargo run -p yachay`).
15
16## Modelo
17
18```text
19  Cell { kind, source, depends_on } ──► Notebook
20        │                                  │
21   content_hash (BLAKE3)            execution_order (topológico)
22        │                                  │
23        └──► digest = BLAKE3(content_hash ‖ digests upstream) ──► notebook_digest
24```
25
26- **Doble estructura**: orden de presentación (lista) + DAG de
27  dependencias. La ejecución sigue el DAG.
28- **Staleness**: editar una celda la marca `Stale` y propaga la
29  obsolescencia a sus descendientes (no a sus ancestros).
30- **Digest Merkle**: el digest de una celda cubre su contenido y todo su
31  linaje; dos notebooks con el mismo `notebook_digest` son
32  reproduciblemente equivalentes. El orden de declaración de
33  dependencias no lo afecta.
34- **Embeds**: una celda puede incrustar la visualización de otro módulo
35  brahman (`dominium`, `pineal`, `takiy`) — yachay integra el ecosistema.
36
37## Dependencias
38
39- `yachay-core` ← `blake3` + `serde`. `#![forbid(unsafe_code)]`.
40- Sin kernel, sin ejecución real, sin UI — tipos puros y deterministas.
41
42## Estado
43
44`yachay-core` implementado y verde (14 tests) + demo CLI. **Pendiente**:
45los kernels de ejecución de código, el render de los embeds (consume los
46`*-render-plan` de cada módulo), persistencia y el frontend GPUI.