1# SDD 06 — Formato `.swm` (Software Mutación)
2
3El `.swm` es la unidad de intercambio de `hammer`. **No es un paquete binario** (`.deb`,
4`.rpm`, ni un `PKGBUILD` que compila quién-sabe-qué). Es un **manifiesto de la mutación**: la
5receta de transformación sobre código fuente público, más las ediciones de configuración. El
6receptor reproduce y verifica localmente; **nunca ejecuta tu binario** (ver
7[SDD 09](09-trust-model.md)).
8
9## 1. Esquema
10
11```yaml
12# my-grep-tweak.swm
13swm_version: 1
14
15base:
16  distro_version: "2026-06-06"      # versión del set base de hammer
17  pins:                              # commits fijados de los upstreams relevantes
18    kernel: "a1b2c3d…"
19    musl:   "e4f5a6b…"
20  # base_hash deriva de pins+distro_version; el receptor verifica compatibilidad
21
22mutations:
23  - type: source_patch              # recompilar una herramienta desde su fuente parcheada
24    repo: "git://git.savannah.gnu.org/grep.git"
25    commit: "a1b2c3d…"              # commit fijado sobre el que aplica el patch
26    patch: |                         # parche .patch de git, embebido o por URL (patch_url)
27      --- a/src/main.c
28      +++ b/src/main.c
29      @@ ...
30    build:
31      compiler: "zig-cc"
32      target: "x86_64-linux-musl"
33      link: "static"
34      flags: ["--enable-perl-regexp"]
35    target_bin: "/bin/grep"
36
37  - type: config_edit               # editar un archivo de config en texto plano
38    file: "/etc/network.conf"
39    inline_diff: |
40      - DHCP=yes
41      + IP=192.168.1.100
42
43  - type: init_rule                 # añadir/ajustar una regla del init (ver SDD 07)
44    action: "watchdog"
45    service: "web"
46    command: "/bin/myweb -p 8080"
47
48signature:                           # opcional pero recomendado (ver SDD 09)
49  by: "sergio"
50  alg: "ed25519"
51  sig: "base64…"
52```
53
54## 2. Tipos de mutación
55
56| `type` | Qué describe | Cómo lo aplica el receptor |
57|---|---|---|
58| `source_patch` | recompilar una herramienta desde fuente parcheada | clona repo@commit → aplica patch → `hammer build` → hidrata en overlay |
59| `config_edit` | edición de un archivo de config | aplica el `inline_diff` (3-way) sobre el archivo objetivo |
60| `init_rule` | regla del bus de init | inyecta la regla vía `/run/init.control` / receta de servicio |
61| `file_drop` | depositar un archivo de datos no compilable | escribe el archivo (con su hash declarado) en la ruta |
62
63Cada `source_patch` es, en esencia, una `Recipe` ([SDD 02](02-build-lab.md)) serializada para
64viajar. El `build` lleva el **compilador por mutación** (no global).
65
66## 3. Aplicación (`hammer apply`)
67
68```
69hammer apply my-grep-tweak.swm
70```
71
721. **Verifica la base.** ¿Los `pins`/`distro_version` son compatibles con el sistema local?
73   Si no, avisa qué difiere y se detiene (o `--force` bajo tu responsabilidad).
742. **Verifica la firma** (si existe) contra las claves de confianza locales.
753. **Reproduce.** Para cada `source_patch`: clona el repo al commit, aplica el patch, compila
76   en el lab local → obtiene un `artifact_hash`.
774. **Aísla.** Hidrata todo en un **overlay temporal** ([SDD 04](04-overlay.md)); aplica
78   `config_edit`/`init_rule`/`file_drop` en esa capa. **No toca el sistema base.**
795. **Valida.** Corres/pruebas en caliente. Si bien → `hammer commit`. Si mal → `hammer discard`.
80
81Nunca se ejecuta un binario ajeno: sólo se transforma código fuente público con una receta que
82tu propio laboratorio compila.
83
84## 4. Determinismo y verificación cruzada
85
86Como el lab es determinista ([SDD 02](02-build-lab.md)), el `artifact_hash` que produce tu
87máquina debe coincidir con el del autor (si declara `expected_hash`). Coincidencia ⇒ obtuviste
88exactamente el mismo binario, sin haberlo descargado. Discrepancia ⇒ algo difiere (toolchain,
89pin, patch) y `hammer` te dice qué. Esto es "verificar, no confiar" en la práctica.
90
91## 5. No-objetivos del formato
92
93- **No** transporta binarios cocidos (salvo `file_drop` para datos no compilables, con hash).
94- **No** es Turing-completo: es declarativo *para el intercambio*, aunque el sistema que
95  describe se viva imperativamente. (Lo declarativo aquí es honesto: describe una
96  transformación, no aprisiona tu sistema.)
97- **No** asume una arquitectura: `target` viaja en cada `source_patch`.
98
99## 6. Interfaz
100
101```rust
102// hammer-core
103#[derive(Serialize, Deserialize)]
104pub struct Swm { /* swm_version, base, mutations, signature */ }
105impl Swm {
106    pub fn from_yaml(s: &str) -> Result<Swm>;
107    pub fn to_yaml(&self) -> Result<String>;
108    pub fn verify_base(&self, local: &BaseRef) -> BaseCompat;
109    pub fn verify_signature(&self, trust: &TrustStore) -> SigStatus;
110}
111```
112
113CLI: `hammer apply <file.swm>` · `hammer export … > out.swm` · `hammer swm verify <file.swm>`.