datekeys-doc/PLAN_formato3_go.md

# Plan: formato 3 en la referencia Go (spec v0.10, entrega 1)

*Estado, 30-09 por la noche: pasos 0 a 8 hechos; la rama `v0.10` está subida, con el tag `spec-v0.10` en `cc35d2c`, y `main` avanzó hasta ella. Detalle en el [handoff](HANDOFF.md), §2.5.*

*30 de septiembre de 2026. Implementa en `datekeys-go`, rama `v0.10`, el texto que el autor aprobó ese día: la entrega 1 del formato 3, con Unicode 18.0.0 y la regla de invisibles. Fuentes: el spec v0.10 de esa rama y [spec_v0.10/formato3_diseno.md](spec_v0.10/formato3_diseno.md). Después, `datekeys-ts` seguirá con su propio plan.*

## Reglas de trabajo

- Cada paso va en su commit, o en varios, sobre la rama `v0.10`, y deja `go test ./...` en verde. Los pasos 6 y 8 pasan además `scripts/check.sh`.
- Nada se sube hasta el paso 8, con la autorización del autor, como en la v0.9.
- Sin dependencias nuevas: las tablas Unicode son código generado, y el generador solo usa la biblioteca estándar.
- Los textos de error siguen el estilo de los actuales, porque `datekeys-ts` los copiará byte a byte.

## Pasos

| Paso | Contenido | Resultado |
|---|---|---|
| 0 | Datos: los 4 ficheros de Unicode 18.0.0 y los 15 de WindowsBestFit, en `.cache/`, fuera de git | Hecho el 30-09: 8,25 MB, con sus SHA-256 |
| 1 | `internal/pathrule`: generador de tablas y reglas de rutas y de texto | Hecho, `6fba1dd`. Falta la salida TypeScript del generador, que pasa al plan de `datekeys-ts` |
| 2 | `capsule`: formato 3 en el códec | Hecho, `72e86b8` |
| 3 | Lector: paso 17 del formato 3 y el sumidero | Hecho, `7249ef4` |
| 4 | Escritor del formato 3 | Hecho, `8955c0f` |
| 5 | CLI | Hecho, `a0de80f` |
| 6 | Datos de prueba | Hecho, de `3c39336` a `18eb3c3` |
| 7 | Documentación y versión | Hecho, `20f9959`; `SpecVersion` pasó a 0.10 en el paso 6 |
| 8 | Verificación y cierre | Hecho, `6fa2b54`; el tag `spec-v0.10`, en `cc35d2c`, con la autorización del autor |

### Paso 1. Tablas y reglas

- **Generador** (`internal/pathrule/gen`): lee `.cache/`, comprueba el SHA-256 de cada fichero y escribe `tables.go`:
  - los puntos asignados, para Cn;
  - `Default_Ignorable_Code_Point`;
  - la descomposición canónica completa y la clase de combinación, para NFD;
  - el pliegue C y F;
  - los caracteres que admiten VS15 y VS16;
  - para cada tabla best-fit, sus puntos no ASCII que van a un byte ASCII.

  Con una bandera escribirá también el módulo TypeScript.
- **Reglas:** una función por regla, con el nombre de la regla en el error, para que Go y TypeScript den el mismo texto. La clave de R7, el árbol de R7 y R9, y las reglas de texto del comentario y del autor.
- **Pruebas:** casos del spec y del diseño; NFD contra `golang.org/x/text` solo en las pruebas, que ya es dependencia indirecta, para los puntos que existen en su versión de Unicode.

### Paso 2. Códec

- `Format3`; `Prelude` acepta `VERSION` 3; el control de versión 3.
- La trama de `BODY` (§29.2) y sus límites.
- `security` (§29.3): el mapa exterior y la evaluación de sus veredictos (§29.7), sin códigos de error.
- El head (§29.4): capas 2 a 4, R1 y R8 en la capa 3, y `ErrHeadInvalid` en la 4; el objeto `Head` en `extension`.

### Paso 3. Lector

- Un sumidero con `Begin(head)`, `Create(i)`, `Commit` y `Abort`. `Open` con solo un `io.Writer` falla tras el paso 2 ante el formato 3, con un error del llamador sin código.
- El paso 17 en subpasos, con su precedencia: un fallo de `age` prevalece; si no, el primer subpaso; los códigos distintos de `ErrIntegrity` solo tras leer hasta EOF.
- `Opened` gana el head, los ficheros y los veredictos. `Inspect` acepta el formato 3.

### Paso 4. Escritor

- `EncryptFiles(dst, files, opts)`: rutas y textos validados, la mtime con su regla, el head con los hashes a cero para medir L, la primera pasada de SHA-256, el sellado, y la segunda pasada, que aborta si un fichero cambió.
- Autodecodificación de los tres CBOR (MUST).
- `Encrypt`, de un solo flujo, pasa a escribir el formato 2 solo tras una opción para los generadores de vectores (§62.1 regla 1).

### Paso 5. CLI

- `encrypt -in` repetible, con ficheros y carpetas recorridas con `Lstat`, solo ficheros regulares, y el nombre de cada carpeta como primer segmento; `-comment`, `-author` y `-no-mtime`.
- `decrypt -out DIR`: `os.Mkdir`, el árbol en `DIR/.datekeys-*` con `os.OpenRoot`, `Root.Rename` tras el paso 18 y `RemoveAll` ante un fallo. Los formatos 1 y 2 siguen escribiendo un fichero.
- La presentación de §29.7: los veredictos, el autor y el comentario con el prefijo y el ancho de la regla, y los veredictos repetidos.

### Paso 6. Datos de prueba

- Fixtures: `format3_single`, `_tree`, `_comment_only`, `_bloque256`, `_time_and_key_portable`, `_area_1024`, `_security_v2`, `_signature_unsupported` y `_seal_unsupported`.
- Vectores: `paths.json`, `path_fold.json`, `head_schema.json`, `security.json`; `cbor.json` con el control de versión 3.
- Mutaciones: las 33 de las dos primeras listas de §64 sobre el formato 3, la lista del formato 3 y los cambios de `VERSION`; el diferencial gana los bloques del formato 3.

### Paso 7. Documentación

README y README.es, CHANGELOG, `docs/traceability.md` y `testdata/README.md`. `SpecVersion` pasa a 0.10 cuando el spec se cierre.

### Paso 8. Cierre

`scripts/check.sh 60s` con los objetivos de fuzzing nuevos (el head, `security` y las rutas), govulncheck, el SHA-256 del spec en `spec/README.md`, y el tag `spec-v0.10` con la autorización del autor.