brahman/docs/changelog/minga.md

# Changelog — minga (semantic_dht)

### feat(minga-vfs): VFS FUSE — el repo como filesystem de sólo lectura
`minga-vfs` deja de ser un stub de 2 LOC: ahora monta el repositorio
direccionado por contenido como un filesystem FUSE navegable con
`ls`/`cat`/`grep`/un editor, sin exponer `sled`.

Layout del montaje:
- `README` — explicación del propio VFS.
- `roots/<hash>` — un archivo por raíz del MST (cada archivo
  ingerido), con el código fuente **reconstruido** en formato
  normalizado. `ls roots/` las enumera todas.
- `cas/<hash>` — la S-expression del subárbol de cualquier hash.
  Este directorio NO se enumera (decenas de miles de nodos) pero
  `cat cas/<hash>` resuelve cualquier hash conocido: es el "blob
  por hash bajo demanda" que la SDD pedía.

Arquitectura, separando por capas (ver feedback de separabilidad):
- **`render`** — `SemanticNode` → texto. Lógica pura, sin IO ni
  FUSE. `render_source` re-imprime los tokens hoja con un
  pretty-printer mínimo consciente de llaves (indenta tras `{`,
  corta tras `;`); `render_sexp` vuelca el árbol literal. El render
  de fuente es normalizado, no byte-exacto: el AST descartó
  whitespace y comentarios al ingerir. Python, cuya estructura vive
  en la indentación, sale como secuencia de tokens — esperado.
- **`source`** — el contrato `NodeSource` (`roots()` + `get()`) y
  `reconstruct()`. Backends: `RepoSource` sobre el `PersistentRepo`
  de `sled`, `MemSource` en RAM (tests / índices efímeros).
- **`fs`** — único módulo acoplado a `fuser`: implementa la
  `Filesystem` trait. Inodos estáticos reservados (1-4), dinámicos
  desde 16 con tabla `(padre, nombre) → inodo` estable. Cada
  archivo se renderiza y cachea en el primer `lookup`.

Dep nueva (workspace + minga-vfs):
- `fuser = "0.15"` con `default-features = false`: prescinde de
  `pkg-config`/`libfuse-dev` en build; el montaje pasa a Rust puro
  (helper `fusermount3` en runtime).

CLI: nuevo subcomando `minga mount <punto>` (`cmd_mount`), que abre
el repo, lo envuelve en `RepoSource` y bloquea hasta
`fusermount -u <punto>`. Pide la passphrase igual que `status`.

Tests: **14** nuevos en minga-vfs (9 unit: render con llaves,
S-expression con campos/escape, parseo de hash de 64 hex, roundtrip
de `MemSource`; 5 integration: ingest→reconstruct lossless a nivel
AST, `roots/` lista todo, vistas source/sexp, deduplicación de
subárboles). Los 10 tests de minga-cli intactos (sin regresión).

Pendientes:
- `cas/` cachea contenido sin tope: navegar un repo gigante crece
  en RAM. Un LRU sería el siguiente paso si molesta.
- Sin extensión en los nombres (`roots/<hash>`): no guardamos el
  lenguaje original, así que el editor no autodetecta sintaxis.

### feat(minga-explorer): listings de items recientes en cada stat card
Iter 12. Hasta ahora minga-explorer mostraba sólo counts (3
números). Ahora cada stat card muestra también un sample de los
items dentro: hashes truncados de los 5 primeros nodos AST
(con su `kind`), atestaciones (`content_hash ← did_short`) y
claves MST. Mucho más útil para debugging que el "tengo N items".

Cambios en `minga-explorer`:
- **`RepoSnapshot` extendido** con 3 nuevos `Vec<...>`:
  - `recent_nodes: Vec<(String, String)>` — `(hash_short, kind)`.
  - `recent_attestations: Vec<(String, String)>` —
    `(content_hash_short, did_short)`.
  - `recent_mst_keys: Vec<String>` — `hash_short`.
  - Cap de 5 items por sección via `RECENT_LIMIT` const.
- **`load_snapshot` itera los stores** y toma los primeros 5
  items via `iter().filter_map(Result::ok).take(RECENT_LIMIT)`.
  Errores per-item se silencian (`filter_map`) — el dashboard
  muestra lo que pueda; un par de items corruptos no debería
  tirar el panel.
- **`short_hash(&str)` helper local**: trunca un hex a sus
  primeros 12 chars (48 bits, distintivo dentro de un repo
  single-machine).
- **`stat_card` extendido**: nuevo arg `recent_items: &[String]`.
  Si no está vacío, agrega un sub-header `"recent (N de TOTAL):"`
  + una linea por item. Cada line es texto pequeño (`px(11)`)
  con el color principal del theme — visualmente queda como
  monospace listing aunque no use mono font (no hay todavía
  en el theme).

Tests: 2 → **4** (+2 sanity de los nuevos defaults + del
`short_hash`).

Beneficio operativo:
- Después de `minga ingest archivo.rs`, el explorer muestra
  inmediatamente los hashes de los nodos AST creados, qué `kind`
  tienen, y las atestaciones firmadas — sin necesitar `minga
  status` o queries SQL.
- "5 de 247" da contexto del crecimiento sin overwhelm de
  listing completo.

Limitación documentada: los "recent" no son cronológicos — sled
ordena lexicográfico por hash. Para timeline real, agregar
timestamp al schema (cambio breaking del store, scope futuro).

### feat(minga-explorer): nueva app dashboard del repo Minga sobre stack yahweh
Iter 11. Cierra el último frente identificado: integración del
módulo Minga (VCS semántico P2P) al ecosistema GUI. Antes Minga
sólo tenía CLI (`minga init/status/ingest/listen/sync/watch`).
Ahora hay un **dashboard GPUI** que muestra los counts del repo
en vivo, sobre el mismo stack themed que las otras dos apps
explorer.

Crate nuevo `crates/apps/minga-explorer/`:
- **Deps**: `minga-store` (para `PersistentRepo::open`) +
  `yahweh-theme` + `yahweh-widget-{banner,card,theme-switcher}`.
  Sin `minga-cli` (no necesita prompts de passphrase) ni
  `minga-core` (counts no requieren parsear AST).
- **Lectura sin passphrase**: el `PersistentRepo` se abre directo
  desde `<repo>/repo` sled. Los counts (`nodes.len()`,
  `attestations.len()`, `mst.len()`) son lectura pública. Para el
  DID se sigue necesitando `minga status` (CLI con passphrase).
- **Refresh por polling cada 2s**: mismo pattern que
  `nakui-explorer`/`nouser-explorer`.
- **3 stat cards** una por dimensión:
  - Nodos AST (cyan) — fragments parseados del código.
  - Atestaciones (verde) — firmas Ed25519 sobre los nodos.
  - Claves MST (purple) — entradas del Merkle Search Tree.
- **Helper `stat_card(cx, label, value, description, accent, ...)`**:
  fabrica una card con border-l colored + label tenue + número
  grande (`px(28)`) + descripción. Reutilizable.
- **Header**: título dinámico (`Repo: <path> · reload <ms> ms`)
  + theme switcher derecha.
- **Error banner**: themed Banner::Error si el repo no abre.
- 2 tests: `load_snapshot_errors_on_missing_dir` (msg claro
  cuando el dir no existe) + sanity del `RepoSnapshot::default`.

Workspace: nueva entry en `members[]`.

Smoke run del binario verificado: bootstrap completo OK, panic
esperado en open_window por falta de display.

Beneficio operativo:
- Un usuario corre `minga init` + `minga ingest archivo.rs` desde
  CLI, después abre `minga-explorer` y ve los counts crecer en
  vivo cuando ingiere más archivos.
- Comparte theme switcher con `nakui-explorer` y
  `nouser-explorer` — cualquier preset elegido se aplica
  visualmente igual cross-app.
- `minga` deja de ser sólo CLI; gana presencia GUI sin tocar
  el resto del módulo.

Apps GUI integradas al stack themed: **4** (nakui-ui, nakui-explorer,
nouser-explorer, minga-explorer).

### feat(minga-core): α-hashing per-language para Python, TypeScript, JavaScript, Go
Cierra el último pendiente fundamentado del CHANGELOG. Cada lenguaje
soportado por `minga` tiene ahora su propio profile α-equivalente —
dos versiones del mismo programa que difieren sólo en nombres de
variables ligadas producen el mismo hash, no importa el lenguaje.
Refactorings tipo "rename variable" no inflan el storage del repo
en ningún dialecto.

Refactor de `alpha.rs` (639 LOC) a módulo `alpha/`:
- **`alpha/common.rs`**: primitives compartidos (TAG_*, write_kind_and_field,
  emit_leaf_marker, emit_binder_body, emit_identifier_ref, push_identifier_name).
  Garantiza que el formato wire del hash sea bit-equivalente entre
  todos los profiles.
- **`alpha/rust.rs`**: la lógica de Rust (movida desde alpha.rs sin
  cambios funcionales).
- **`alpha/python.rs`**: nuevo.
- **`alpha/ecmascript.rs`**: nuevo (cubre TypeScript + JavaScript;
  comparten la mayoría de los kinds).
- **`alpha/go.rs`**: nuevo.
- **`alpha/mod.rs`**: re-exporta `hash_node_alpha` (Rust legacy) +
  expone `hash_alpha_with(dialect, node)` que despacha al profile
  correspondiente.

Cobertura per-language:

**Python** (`def`, `lambda`, `for`, comprehensions, `with`):
- `function_definition` y `lambda`: parámetros (incluyendo
  typed_parameter, default_parameter, *args, **kwargs) introducen
  binders al body. El nombre de la función NO es α-anónimo.
- `for_statement`: el `left` (identifier o tuple) introduce
  binder(es) al body.
- `list_comprehension`, `set_comprehension`, `dictionary_comprehension`,
  `generator_expression`: cada `for_in_clause` añade binders que
  viven en el body + clauses siguientes (semántica de scope
  incremental de Python).
- `with_statement`: `as` introduce binder al body (recursando en
  `as_pattern_target` para llegar al identifier).

**ECMAScript** (TS + JS):
- `function_declaration`, `function_expression`, `method_definition`,
  `generator_function_*`: parameters → body. Soporta TS
  `required_parameter` y `optional_parameter` (`x: number`,
  `x?: number`).
- `arrow_function`: tanto `(x, y) => body` como shorthand `x => body`.
- `statement_block`: `lexical_declaration` (let/const) y
  `variable_declaration` (var) introducen binders al resto del block.
- `for_in_statement` (cubre `for-of` y `for-in`): `left` → body.
- `for_statement` (C-style): initializer (lexical decl) introduce
  binders al condition + increment + body.
- `catch_clause`: parameter → body.

**Go**:
- `function_declaration`, `method_declaration`, `func_literal` (closure):
  `parameter_list` → body. `parameter_declaration` con varios names
  agrupa varios binders bajo un mismo tipo (`a, b int`).
- `block`: `short_var_declaration` (`x := ...`) introduce binders
  al resto.
- `for_statement` con `range_clause` (`for k, v := range m`): los
  identifiers del `left` son binders al body.
- `for_statement` con `for_clause` (C-style): initializer → body.
- `if_statement` con `initializer` (`if x := init(); x > 0`):
  binders viven en condition + consequence + alternative.

API:
- `hash_alpha_with(Dialect, &SemanticNode) -> ContentHash` —
  despacho per-dialect.
- `hash_node_alpha(&SemanticNode) -> ContentHash` — alias histórico
  asume Rust (back-compat).

Tests: 26 nuevos en `tests/alpha_polyglot.rs`:
- Python (9): def rename, lambda rename, for-loop rename, list comp,
  nested comp, with rename, function name matters, iterable name
  matters, sanity negativo (operación distinta → hash distinto).
- JS/TS (9): function rename, function name matters, arrow rename,
  arrow shorthand rename, let/const rename, for-of rename, classic
  for rename, catch rename, TS typed param rename, TS type matters.
- Go (6): function rename, function name matters, short var decl
  rename, range_clause rename, if-init rename, func_literal closure
  rename.
- Cross-language (1): mismos shapes en lenguajes distintos
  producen hashes distintos (sanity para evitar colisiones).

141 tests verdes en minga-core (115 antes; +26 polyglot). Refactor
sin regresión: 36 α-Rust tests siguen pasando.

Pendientes que quedan en Minga (orden de prioridad):
- `minga-vfs` FUSE (proyecto independiente, scope grande).
- Cobertura adicional por-lenguaje: Python class, JS destructuring,
  Go type_switch, etc. — cada uno pequeño, no urgente.

### feat(minga-core): cierre del α-hashing de Rust — if let, while let, let-else, or-pattern, let-chains
Cierra los 5 pendientes documentados en `alpha.rs`. El hash
α-equivalente ahora es estable bajo renombre de TODOS los binders
de Rust, no sólo los del MVP (parámetros, let, for, match arms).

Pendientes cerrados:
- **`if let X = expr { ... }`**: `if_expression` detecta
  `let_condition` en su `condition`, recolecta los binders del
  pattern, los propaga al `consequence`. El `alternative` (else)
  NO los ve.
- **`while let X = expr { ... }`**: simétrico al if-let, propaga al
  `body`. El `condition` mismo se evalúa con scope previo (los
  binders todavía no existen).
- **`let-else`**: `let_declaration` con campo `alternative`. El
  alternative se procesa con el scope ANTES de los binders (ya
  funcionaba: `feed_let` llama `feed` para no-pattern children con
  el scope actual; `feed_block` extiende el scope DESPUÉS de
  `feed_let`).
- **`or_pattern`**: en `pat1 | pat2` (Rust enforcement: ambos lados
  introducen los mismos binders). Para emit, recorremos cada lado
  con `feed_pattern`. Para collect, sólo el primer lado — iterar
  todos duplicaría binders y rompería los índices de Bruijn.
- **let-chains** (`if let X = a && let Y = b { ... }`): el
  `collect_let_condition_binders` recursa en el árbol del condition,
  capturando todos los `let_condition` (vivan dentro de
  `binary_expression` u otros nodos). Ambos binders quedan en scope
  del consequence.

Helper nuevo: `feed_let_condition` para que el `pattern` del
let_condition pase por `feed_pattern` (que distingue binders vs
constructors). Sin esto, los identifiers del pattern se hasheaban
como variables libres y `Some(x)` ≠ `Some(y)` aún teniendo el
mismo significado.

Tests: 6 nuevos en `tests/alpha_invariants.rs`:
- `alpha_if_let_binder_rename_invariant`
- `alpha_if_let_else_does_not_see_binder` (sanity)
- `alpha_while_let_binder_rename_invariant`
- `alpha_let_else_binder_rename_invariant`
- `alpha_or_pattern_binder_rename_invariant`
- `alpha_let_chain_binders_propagate_to_consequence`
- `alpha_if_let_does_not_collide_with_unrelated_program` (negativo:
  programas distintos NO deben dar el mismo hash)

36 tests α verdes (eran 30). 115 tests totales en minga-core.

Lo que esto significa: el hash α-equivalente de Rust en minga es
**completo** — cubre todos los constructos del lenguaje que
introducen bindings. Dos versiones del mismo programa que difieren
sólo en nombres de variables (incluyendo en `if let`, `while let`,
`or-pattern`, etc.) producen el mismo hash y por tanto la misma
identidad CAS. Refactorings del tipo "rename variable" no inflan
el storage del repo.

Pendientes futuros:
- α-hashing per-language (Python: def/lambda/comprehensions; TS/JS:
  function/arrow/destructuring; Go: func/closure). Cada uno
  requiere conocimiento profundo de la gramática y tests
  exhaustivos. Plantilla genérica no aplica.

### feat(minga): multi-lenguaje en parser — Python, TypeScript, JavaScript, Go
Minga deja de ser Rust-only. Cualquiera de los cinco dialectos
(Rust + 4 nuevos) se ingresa al CAS por su AST normalizado, hashea
estructuralmente, sincroniza por DHT como cualquier nodo. La
auto-detección por extensión hace que `minga ingest archivo.py` o
`.ts` o `.go` "simplemente funcione".

API nueva en `minga_core::parse`:
- Funciones por dialecto (~6 LOC c/u sobre el `parse_with` común):
  `python`, `typescript`, `javascript`, `go`. Más la `rust` existente.
- Enum `Dialect` con `parse(source) -> Result<SemanticNode>` y
  `name() -> &'static str` para logging.
- `detect_by_extension(ext) -> Option<Dialect>`: mapea `rs`/`py`/
  `pyi`/`ts`/`js`/`mjs`/`cjs`/`go` (case-insensitive). `None` para
  extensiones desconocidas — el caller decide si es error o se
  ignora silente.

Wire en `minga-cli`:
- `cmd_ingest` deja de hardcodear `parse::rust` — usa
  `detect_dialect(file)?.parse(...)`. Acepta `.py`, `.ts`, `.js`,
  `.go` además de `.rs`.
- `initial_scan` y `cmd_watch` cambian `is_rs_file` → `is_supported_source`
  para incluir todas las extensiones soportadas en el filtro.
- `CliError::UnsupportedLanguage { path, extension }` nuevo, con
  mensaje que lista las extensiones reconocidas.

Notas sobre hashing:
- El AST normalizado (`SemanticNode`) descarta whitespace y
  comentarios — propiedad universal de tree-sitter (extras). Misma
  lógica para los 5 dialectos.
- Hashing **estructural** (`cas::hash_node`) funciona para todos:
  dos textos semánticamente equivalentes-por-estructura producen el
  mismo hash. NO α-equivalente (las variables ligadas distinguen).
- Hashing **α-equivalente** (`alpha::hash_node_alpha`) sigue siendo
  Rust-only: cada lenguaje tiene reglas distintas para qué es
  binder vs. constructor (def/lambda en Python, arrow functions en
  TS/JS, func + closures en Go). Implementación per-language queda
  como work futuro — requiere conocimiento profundo de cada
  gramática y no se plantilla genéricamente.
- Sanity test `structural_hash_distinguishes_languages` verifica
  que `x = 1` parseado como Python ≠ parseado como JavaScript: las
  gramáticas no comparten kinds y los hashes salen distintos.
  Importante para evitar colisiones cuando el mismo source se
  ingresa bajo dialectos distintos.

Deps nuevas (workspace + minga-core):
- `tree-sitter-python = "0.23"`
- `tree-sitter-typescript = "0.23"` (sólo el modo `LANGUAGE_TYPESCRIPT`,
  no TSX — bumpear a TSX es agregar otro dialecto cuando se necesite).
- `tree-sitter-javascript = "0.23"`
- `tree-sitter-go = "0.23"`

Tests:
- 9 nuevos en `parse::tests`: parse básico para los 5 dialectos
  (Python con type hints, TS con tipos, JS sin tipos, Go con
  package declaration), `detect_by_extension` canonical +
  case-insensitive, `dialect_name`, `structural_hash_distinguishes_languages`.
- 108 tests verdes en minga-core (39 → 48 unit + integration tests
  pre-existentes intactos).
- 10 tests verdes en minga-cli (sin regresión en el path Rust;
  el refactor a `detect_dialect`/`is_supported_source` no rompe
  nada).

Pendientes futuros del changelog:
- α-hashing per-language (Python: def/lambda/comprehensions;
  TS/JS: function/arrow/destructuring; Go: func/closure). Trabajo
  profundo, scope independiente.
- α-Rust pendientes documentados en `alpha.rs`: `if let`,
  `while let`, `let-else`, let-chains, `or_pattern` con bindings.