sergio/takana

> Una distribución Linux construida con un laboratorio funcional y hermético en el > sótano, y una terminal mutable, clásica y anárquica en el piso de arriba — diseñada > desde el suelo para que una IA programadora entienda, modifique y co…

TOML 188Rust 55Shell 30Markdown 281211 Definiciones

Clonar por HTTPS, con el git de siempre

⎇ 42288230f9560814e356586d8b9eeb36747b95fc docs/10-roadmap.md Markdown · 170 líneas · 10.5 KB Historia crudo

Fase 5: política de caps del bus desde agent-caps.toml 42288230f · Sergio · hace 4 meses

1# SDD 10 — Roadmap
2
3## Estrategia: validar la capa AI-nativa sobre Alpine antes de la distro propia
4
5La innovación de `hammer` no es la distro — es el substrato AI-nativo (build determinista +
6mutable + diario + `.swm`). Construir bootstrap + init + userland de cero antes de validar esa
7capa sería arriesgar meses contra una hipótesis no probada. Por eso:
8
9> **Fase 0–6:** montamos `hammer` **sobre Alpine** (musl + busybox + FHS mutable, ya cocidos).
10> Validamos el bucle completo en semanas.
11> **Track posterior:** una vez probado, bajamos a distro propia (init propio, bootstrap propio,
12> userland propio) reusando todo el tooling sin retrabajo.
13
14Ver [ADR 0002](adr/0002-alpine-first.md).
15
16---
17
18## Fases (sobre Alpine)
19
20### Fase 0 — Laboratorio de build  ✅
21- [x] `hammer-core`: tipos `Recipe`, `ArtifactHash`, `Store` (BLAKE3, layout `/store`).
22- [x] `hammer-build`: sandbox con `bubblewrap` + `zig cc` → binario musl estático.
23- [x] CAS: hashing de entrada, caché por hash, sellado en el store.
24- [x] `hammer build <recipe.toml>` → imprime el hash del artefacto.
25- [x] Fuente git **y** tarball (sha256 fijado), patches opcionales.
26- [x] Heurística de build system: autotools / cmake / meson / make plano.
27- [x] Caché persistente de zig entre builds (~30s/build ahorrados).
28
29### Fase 1 — Hidratación ✅
30- [x] `hydrate(hash, target, mode)`: hardlink a FHS, `patchelf` para el caso dinámico.
31- [x] `hammer hydrate <hash> --into /`.
32
33### 🎯 Primer entregable (Fase 0 + 1) ✅
34**GNU grep 3.12 compilado estático desde el tarball upstream, sellado en el store
35(`b3:b81e893e…`), hidratado por hardlink a `/usr/bin/grep` y ejecutado dentro del rootfs
36Alpine vía `bwrap`** — confirma el corazón "fábrica funcional → FHS mutable" sobre el
37substrato Alpine. La VM/LXC dedicada queda como ejercicio de empaque, no como
38pre-requisito de validación.
39
40### Fase 2 — Overlay de experimentación  ✅
41- [x] Crate `hammer-overlay`: `try` / `commit` / `discard` / `status` sobre `overlayfs`.
42- [x] Manifiesto persistente en `<state_root>/<id>/state.json`; `status` enumera.
43- [x] `commit` promociona archivos y procesa whiteouts (char dev 0/0) como remove.
44- [x] Subcomandos del CLI: `hammer try [targets…]`, `commit <id>`, `discard <id>`, `status`.
45- [x] Tests E2E con bwrap+user-ns, gateados en `HAMMER_OVERLAY_TESTS=1` (kernel-dependiente).
46- [x] Hook al diario en `commit` (Fase 3 lo añadió vía `commit_with_journal`).
47- [ ] Anidación real de overlays (un solo overlay activo por target hoy).
48
49### Fase 3 — Diario de mutaciones  ▶ *en progreso*
50- [x] Crate `hammer-journal`: `MutationEvent`, `Source` (HammerHydrate/HammerCommit/External),
51      append/read/tail/follow JSON-líneas. RFC 3339 sin chrono.
52- [x] `hammerd` con `fanotify` (FAN_CLOSE_WRITE) sobre `/bin`,`/sbin`,`/usr/bin`,`/usr/sbin`,
53      `/lib`,`/usr/lib`,`/etc`. Filtra eventos bajo overlays activos. Fallback graceful sin
54      CAP_SYS_ADMIN.
55- [x] `hammer journal [--tail N] [--follow] [--format pretty|json]`.
56- [x] `hammer commit` registra cada archivo promocionado vía `commit_with_journal`.
57- [ ] Refinar op del watcher (Create vs Replace vs Edit con FAN_REPORT_DFID_NAME).
58- [ ] Hash del contenido tras la mutación (`content_hash`) y de-dup idempotente.
59
60### Fase 4 — Formato y flujo `.swm`  ▶ *en progreso*
61- [x] `Swm` de/serialización YAML estable (roundtrip).
62- [x] `verify_schema` (estructura + invariantes por mutación) y `verify_base` (distro_version
63      + pins) con `BaseRef` / `BaseCompat`.
64- [x] `apply_config_edit` (hunks `-/+` con búsqueda exacta, no-fuzz) y `apply_file_drop`
65      (base64 inline + verificación BLAKE3 vs `content_hash`).
66- [x] Bridge `Mutation::SourcePatch` → `Recipe` + `build` + hidratación.
67- [x] CLI: `hammer apply [--prefix DIR] [--base-ref base.json]`,
68      `hammer swm-verify`, `hammer export --journal DIR > out.swm`.
69- [ ] `patch_url` / `content_url` remotos (hoy sólo inline).
70- [x] Provenance en `export`: mapa artefacto→receta vía sidecar `.hammer/recipe.toml` que
71      `hammer-build::build` escribe dentro del artefacto antes de sellar. `hammer export`
72      agrupa eventos por `artifact_hash` y emite UN `source_patch` por grupo cuya receta
73      sea recuperable; lo demás cae al fallback `file_drop`. Source `git` modelado;
74      `tarball` cae a file_drop con warning (pendiente extender SourcePatch).
75- [x] Firma `signature` (ed25519) y `TrustStore` local. `hammer_core::sign`: `KeyPair`
76      (genera/carga/escribe claves), `TrustStore::load(dir)` (lee `*.ed25519.pub`),
77      `Swm::verify_signature(&trust) → SigStatus` (`trusted`/`unknown-key`/`bad-sig`/
78      `unsigned`) sobre bytes canónicos JSON del manifiesto sin la firma. CLI:
79      `hammer keygen`, `hammer swm-sign`, y `hammer swm-verify --trust DIR`. La firma reporta
80      autoría/integridad; NO autoriza promover (sigue mandando reproducir + commit). SDD 09 §3,§5.
81- **Hecho cuando:** exportas un cambio, lo aplicas en otra máquina y reproduce idéntico.
82      ✅ Demostrado en `crates/hammer-cli/tests/swm_roundtrip.rs` para
83      `config_edit` + `file_drop`. `source_patch` reusa el camino de Fase 0/1 (gated en
84      `HAMMER_NETWORK_TESTS`).
85
86### Fase 5 — Bus de agente  ▶ *en progreso*
87- [x] `/run/init.control` (FIFO humano): `mkfifo`, reader que loguea cada línea, y
88      `hammer ctl <line>` que escribe al FIFO con error claro si no existe.
89- [x] `/run/agent.sock` (JSON-líneas) con handshake `Hello/Welcome`, auth via
90      `SO_PEERCRED` y `CapsPolicy` por UID.
91- [x] Comandos `Compile`/`Inject`/`Query`/`Init`; eventos
92      `Welcome`/`BuildReady`/`BuildFailed`/`Injected`/`QueryResult`/`InitAck`/
93      `Modified`/`Crashed`/`Error`.
94- [x] EventBus in-process: el watcher publica `Modified` y todas las conexiones lo reciben.
95- [x] Subsistemas independientes en `hammerd::main` (FIFO/watcher/bus en threads); si uno
96      falla en init, los demás siguen.
97- [x] Política expresiva leída de `/etc/hammer/agent-caps.toml` (`hammerd --agent-caps`).
98      `hammer_core::AgentCapsConfig`: `default` + `[[rule]]` por `uid`/`gid` (primera que casa
99      gana), `caps_for(uid,gid)`. `bus::policy_from_config` la enchufa; sin fichero o con
100      fichero inválido, cae a la política por-UID por defecto (avisando). Ejemplo en
101      `examples/agent-caps.toml`. El `default_policy` hardcoded queda como fallback.
102- [ ] `CRASHED` real (requiere supervisión de servicios, que llega con el init propio del
103      track posterior).
104- [ ] `BuildFailed.log_tail` con cola real del lab (hoy es `None`; el `reason` viene del
105      `Error` de Rust pero no se conserva el log textual del sandbox).
106- **Hecho cuando:** un cliente externo dispara un build y recibe el evento de fin por el
107  socket. ✅ Camino implementado (`Compile` → `BuildReady`/`BuildFailed`) y la maquinaria
108  alrededor cubierta por `crates/hammerd/tests/bus_e2e.rs`: handshake con peer creds,
109  gating `no_cap`, `Query`, `Modified` fan-out, `Init`→FIFO. Un `Compile` real reusa el
110  camino de Fase 0/1 (gated en `HAMMER_NETWORK_TESTS`).
111
112### Fase 6 — Integración de la IA  ▶ *en progreso*
113- [x] Crate `hammer-agent` con tres piezas:
114      - `AgentClient`: cliente síncrono del bus (handshake, `compile`/`inject`/`query`/`init`
115        bloqueantes, drenado de eventos asíncronos).
116      - `IntentTranslator` (trait) + `MockTranslator` cargado desde un `IntentCatalog` YAML
117        (intent → `.swm` pre-armado). La integración con un LLM real se enchufa detrás del
118        mismo trait sin tocar el bucle.
119      - `Orchestrator` con `run(intent) → Proposal`: plan → schema → base → try (overlay
120        o prefix) → apply (mutaciones puras + source_patch vía bus opcional) → verify →
121        propose.
122- [x] CLI: `hammer ai <intent> --catalog F [--prefix DIR --base-ref F --bus SOCK]`.
123- [x] Tipos del protocolo del bus movidos a `hammer-core::proto` para que `hammerd` y
124      `hammer-agent` los compartan.
125- [x] Tests:
126      - 10 unit en `hammer-agent` (translator + catalog + orchestrator).
127      - 3 e2e del bucle agéntico (prefix tmp → archivos esperados en disco).
128      - 1 e2e del cliente contra un *stub* del bus (handshake + Compile→BuildReady + Modified
129        asíncrono).
130- [x] Traductor LLM real (Claude API u otro), opcional vía feature flag o crate aparte.
131      `ClaudeTranslator` detrás de la feature `llm-claude`, con `ureq + rustls`. Modelo
132      por defecto `claude-opus-4-8`, adaptive thinking + `effort=high`. Trait `HttpClient`
133      inyectable para tests sin red. CLI: `hammer ai --llm` (mutuamente excluyente con
134      `--catalog`). Sin la feature, el flag falla con mensaje claro.
135- [x] Lenguaje de consulta del sistema (SDD 08 §6) para que la IA refiera servicios y
136      archivos sin rutas frágiles. Forma `kind:value` (`bin`, `file`, `pin`, `service`,
137      `depends`), evaluable local (`hammer query <expr>`) y remoto vía bus
138      (`Command::Query{what:"expr"}`). Parser ELF64 mínimo para extraer `DT_NEEDED`.
139- [x] Bucle de auto-reparación (cliente reacciona a `Crashed` con un nuevo plan).
140      `Orchestrator::run_with_repair(intent, &RepairPolicy)` drena async events del bus
141      tras cada apply; si llega `Crashed`, formatea una nueva intención y reentra hasta
142      `max_attempts`. El `Proposal` final lleva el `repair_chain` completo para que el
143      humano vea la evolución antes de hacer commit. CLI: `hammer ai --repair-max-attempts`.
144- **Hecho cuando:** una intención en lenguaje natural produce un cambio probado en overlay,
145  presentado para `commit` humano. ✅ Demostrado por `hammer ai` con `MockTranslator`:
146  intent → `.swm` → mutaciones aplicadas → `Proposal` con `overlay_id` + checks. El humano
147  decide `commit`/`discard`. El upgrade a LLM real reusa todo el bucle.
148
149---
150
151## Track posterior — distro propia
152- Reemplazar el init de Alpine por **tu init** (bus por pipes nativo).
153- **Bootstrap from-scratch** con `zig`/`musl-cross-make` (Stage 0/1/2 → imagen destino).
154- Userland propio (busybox/toybox a elección), `/etc/service/*` propios.
155- Decidir particionado/montaje de `/store` y `/var/lib/hammer`.
156- Log de transparencia para compartir en comunidad ([SDD 09](09-trust-model.md) §4).
157- Mini-lenguaje de consulta del sistema para la IA ([SDD 08](08-ai-integration.md) §6).
158
159---
160
161## Estado actual
162- ✅ Repo y workspace Rust inicializados.
163- ✅ SDDs y ADRs redactados.
164- ✅ Esqueletos de crates que compilan (`hammer build` stub).
165- ⏭️ Siguiente: implementar el sandbox de build real (Fase 0) y montar la VM/LXC Alpine.
166
167## Notas de entorno
168- Desarrollo principal: laptop del autor.
169- Host actual: Proxmox (`gioser.net`). La VM/LXC Alpine de pruebas vivirá aquí o en la laptop.
170- Repo: `https://gitea.gioser.net/sergio/hammer`.

10-roadmap.md

SDD 10 — Roadmap

Estrategia: validar la capa AI-nativa sobre Alpine antes de la distro propia

La innovación de hammer no es la distro — es el substrato AI-nativo (build determinista + mutable + diario + .swm). Construir bootstrap + init + userland de cero antes de validar esa capa sería arriesgar meses contra una hipótesis no probada. Por eso:

Fase 0–6: montamos hammer sobre Alpine (musl + busybox + FHS mutable, ya cocidos). Validamos el bucle completo en semanas. Track posterior: una vez probado, bajamos a distro propia (init propio, bootstrap propio, userland propio) reusando todo el tooling sin retrabajo.

Ver ADR 0002.

Fases (sobre Alpine)

Fase 0 — Laboratorio de build ✅

hammer-core: tipos Recipe, ArtifactHash, Store (BLAKE3, layout /store).
hammer-build: sandbox con bubblewrap + zig cc → binario musl estático.
CAS: hashing de entrada, caché por hash, sellado en el store.
hammer build <recipe.toml> → imprime el hash del artefacto.
Fuente git y tarball (sha256 fijado), patches opcionales.
Heurística de build system: autotools / cmake / meson / make plano.
Caché persistente de zig entre builds (~30s/build ahorrados).

Fase 1 — Hidratación ✅

hydrate(hash, target, mode): hardlink a FHS, patchelf para el caso dinámico.
hammer hydrate <hash> --into /.

🎯 Primer entregable (Fase 0 + 1) ✅

GNU grep 3.12 compilado estático desde el tarball upstream, sellado en el store (b3:b81e893e…), hidratado por hardlink a /usr/bin/grep y ejecutado dentro del rootfs Alpine vía bwrap — confirma el corazón "fábrica funcional → FHS mutable" sobre el substrato Alpine. La VM/LXC dedicada queda como ejercicio de empaque, no como pre-requisito de validación.

Fase 2 — Overlay de experimentación ✅

Crate hammer-overlay: try / commit / discard / status sobre overlayfs.
Manifiesto persistente en <state_root>/<id>/state.json; status enumera.
commit promociona archivos y procesa whiteouts (char dev 0/0) como remove.
Subcomandos del CLI: hammer try [targets…], commit <id>, discard <id>, status.
Tests E2E con bwrap+user-ns, gateados en HAMMER_OVERLAY_TESTS=1 (kernel-dependiente).
Hook al diario en commit (Fase 3 lo añadió vía commit_with_journal).
Anidación real de overlays (un solo overlay activo por target hoy).

Fase 3 — Diario de mutaciones ▶ en progreso

Crate hammer-journal: MutationEvent, Source (HammerHydrate/HammerCommit/External), append/read/tail/follow JSON-líneas. RFC 3339 sin chrono.
hammerd con fanotify (FAN_CLOSE_WRITE) sobre /bin,/sbin,/usr/bin,/usr/sbin, /lib,/usr/lib,/etc. Filtra eventos bajo overlays activos. Fallback graceful sin CAP_SYS_ADMIN.
hammer journal [--tail N] [--follow] [--format pretty|json].
hammer commit registra cada archivo promocionado vía commit_with_journal.
Refinar op del watcher (Create vs Replace vs Edit con FAN_REPORT_DFID_NAME).
Hash del contenido tras la mutación (content_hash) y de-dup idempotente.

Fase 4 — Formato y flujo `.swm` ▶ en progreso

Swm de/serialización YAML estable (roundtrip).
verify_schema (estructura + invariantes por mutación) y verify_base (distro_version + pins) con BaseRef / BaseCompat.
apply_config_edit (hunks -/+ con búsqueda exacta, no-fuzz) y apply_file_drop (base64 inline + verificación BLAKE3 vs content_hash).
Bridge Mutation::SourcePatch → Recipe + build + hidratación.
CLI: hammer apply [--prefix DIR] [--base-ref base.json], hammer swm-verify, hammer export --journal DIR > out.swm.
patch_url / content_url remotos (hoy sólo inline).
Provenance en export: mapa artefacto→receta vía sidecar .hammer/recipe.toml que hammer-build::build escribe dentro del artefacto antes de sellar. hammer export agrupa eventos por artifact_hash y emite UN source_patch por grupo cuya receta sea recuperable; lo demás cae al fallback file_drop. Source git modelado; tarball cae a file_drop con warning (pendiente extender SourcePatch).
Firma signature (ed25519) y TrustStore local. hammer_core::sign: KeyPair (genera/carga/escribe claves), TrustStore::load(dir) (lee *.ed25519.pub), Swm::verify_signature(&trust) → SigStatus (trusted/unknown-key/bad-sig/ unsigned) sobre bytes canónicos JSON del manifiesto sin la firma. CLI: hammer keygen, hammer swm-sign, y hammer swm-verify --trust DIR. La firma reporta autoría/integridad; NO autoriza promover (sigue mandando reproducir + commit). SDD 09 §3,§5.
Hecho cuando: exportas un cambio, lo aplicas en otra máquina y reproduce idéntico. ✅ Demostrado en crates/hammer-cli/tests/swm_roundtrip.rs para config_edit + file_drop. source_patch reusa el camino de Fase 0/1 (gated en HAMMER_NETWORK_TESTS).

Fase 5 — Bus de agente ▶ en progreso

/run/init.control (FIFO humano): mkfifo, reader que loguea cada línea, y hammer ctl <line> que escribe al FIFO con error claro si no existe.
/run/agent.sock (JSON-líneas) con handshake Hello/Welcome, auth via SO_PEERCRED y CapsPolicy por UID.
Comandos Compile/Inject/Query/Init; eventos Welcome/BuildReady/BuildFailed/Injected/QueryResult/InitAck/ Modified/Crashed/Error.
EventBus in-process: el watcher publica Modified y todas las conexiones lo reciben.
Subsistemas independientes en hammerd::main (FIFO/watcher/bus en threads); si uno falla en init, los demás siguen.
Política expresiva leída de /etc/hammer/agent-caps.toml (hammerd --agent-caps). hammer_core::AgentCapsConfig: default + [[rule]] por uid/gid (primera que casa gana), caps_for(uid,gid). bus::policy_from_config la enchufa; sin fichero o con fichero inválido, cae a la política por-UID por defecto (avisando). Ejemplo en examples/agent-caps.toml. El default_policy hardcoded queda como fallback.
CRASHED real (requiere supervisión de servicios, que llega con el init propio del track posterior).
BuildFailed.log_tail con cola real del lab (hoy es None; el reason viene del Error de Rust pero no se conserva el log textual del sandbox).
Hecho cuando: un cliente externo dispara un build y recibe el evento de fin por el socket. ✅ Camino implementado (Compile → BuildReady/BuildFailed) y la maquinaria alrededor cubierta por crates/hammerd/tests/bus_e2e.rs: handshake con peer creds, gating no_cap, Query, Modified fan-out, Init→FIFO. Un Compile real reusa el camino de Fase 0/1 (gated en HAMMER_NETWORK_TESTS).

Fase 6 — Integración de la IA ▶ en progreso

Crate hammer-agent con tres piezas: - AgentClient: cliente síncrono del bus (handshake, compile/inject/query/init bloqueantes, drenado de eventos asíncronos). - IntentTranslator (trait) + MockTranslator cargado desde un IntentCatalog YAML (intent → .swm pre-armado). La integración con un LLM real se enchufa detrás del mismo trait sin tocar el bucle. - Orchestrator con run(intent) → Proposal: plan → schema → base → try (overlay o prefix) → apply (mutaciones puras + source_patch vía bus opcional) → verify → propose.
CLI: hammer ai <intent> --catalog F [--prefix DIR --base-ref F --bus SOCK].
Tipos del protocolo del bus movidos a hammer-core::proto para que hammerd y hammer-agent los compartan.
Tests: - 10 unit en hammer-agent (translator + catalog + orchestrator). - 3 e2e del bucle agéntico (prefix tmp → archivos esperados en disco). - 1 e2e del cliente contra un stub del bus (handshake + Compile→BuildReady + Modified asíncrono).
Traductor LLM real (Claude API u otro), opcional vía feature flag o crate aparte. ClaudeTranslator detrás de la feature llm-claude, con ureq + rustls. Modelo por defecto claude-opus-4-8, adaptive thinking + effort=high. Trait HttpClient inyectable para tests sin red. CLI: hammer ai --llm (mutuamente excluyente con --catalog). Sin la feature, el flag falla con mensaje claro.
Lenguaje de consulta del sistema (SDD 08 §6) para que la IA refiera servicios y archivos sin rutas frágiles. Forma kind:value (bin, file, pin, service, depends), evaluable local (hammer query <expr>) y remoto vía bus (Command::Query{what:"expr"}). Parser ELF64 mínimo para extraer DT_NEEDED.
Bucle de auto-reparación (cliente reacciona a Crashed con un nuevo plan). Orchestrator::run_with_repair(intent, &RepairPolicy) drena async events del bus tras cada apply; si llega Crashed, formatea una nueva intención y reentra hasta max_attempts. El Proposal final lleva el repair_chain completo para que el humano vea la evolución antes de hacer commit. CLI: hammer ai --repair-max-attempts.
Hecho cuando: una intención en lenguaje natural produce un cambio probado en overlay, presentado para commit humano. ✅ Demostrado por hammer ai con MockTranslator: intent → .swm → mutaciones aplicadas → Proposal con overlay_id + checks. El humano decide commit/discard. El upgrade a LLM real reusa todo el bucle.

Track posterior — distro propia

Reemplazar el init de Alpine por tu init (bus por pipes nativo).
Bootstrap from-scratch con zig/musl-cross-make (Stage 0/1/2 → imagen destino).
Userland propio (busybox/toybox a elección), /etc/service/* propios.
Decidir particionado/montaje de /store y /var/lib/hammer.
Log de transparencia para compartir en comunidad (SDD 09 §4).
Mini-lenguaje de consulta del sistema para la IA (SDD 08 §6).

Estado actual

✅ Repo y workspace Rust inicializados.
✅ SDDs y ADRs redactados.
✅ Esqueletos de crates que compilan (hammer build stub).
⏭️ Siguiente: implementar el sandbox de build real (Fase 0) y montar la VM/LXC Alpine.

Notas de entorno

Desarrollo principal: laptop del autor.
Host actual: Proxmox (gioser.net). La VM/LXC Alpine de pruebas vivirá aquí o en la laptop.
Repo: https://gitea.gioser.net/sergio/hammer.