- README: the state, with the modules of stage 1 and how its integers
are exact on the VM and on the web, and how to run the tests compiled
to JavaScript, which the gate does not run.
- CHANGELOG: stage 1.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ -4,6 +4,23 @@ Cambios notables de la librería Dart. El proyecto usa versionado semántico; mi
## Especificación 0.11, en la rama `v0.11` — sin versión
### Etapa 1: errores, bytes, CBOR y DER (05-10-2026)
- **Errores normativos (§69).**`ErrorCode` con los 19 códigos en el orden del spec y `DateKeysException`, con el mensaje `contexto: CÓDIGO` de Go. `wrap` y `withContext` hacen lo que `fmt.Errorf("prefijo: %w")`, y `errorCode` lo que `datekeys.Code`. Una prueba compara el catálogo con las líneas `ERR_` del §69, leído de `datekeys-go` en el tag `spec-v0.11`.
- **Bytes.** Hexadecimal, comparación y concatenación.
- UTF-8 estricto: rechaza lo que rechaza `utf8.Valid` de Go y conserva un U+FEFF inicial. El `Utf8Decoder` de `dart:convert` lo descarta, en la VM y en la web, así que no se usa.
- Un `String` con un surrogate suelto se escribe en UTF-8 generalizado (WTF-8), que no es UTF-8 válido.
- `utf8.DecodeRune` y el `%q` de Go (`strconv.Quote`). La tabla de `strconv.IsPrint` de Go 1.26 se copia de `datekeys-ts`, y una prueba fija el SHA-256 del conjunto de runas.
- **CBOR (§58, §58.1).** Port de `codec/codec.go`: `CborEncoder`, `CborDecoder`, `unmarshalCbor`, `peekSchema`, `checkSchema` y `walkCbor`, con los mismos textos de error.
- Los enteros son exactos en la VM y en la web: un `int` hasta 2^53-1 y un `BigInt` por encima, también en las claves de los mapas y en los textos de error.
- El `Encoder` de Go rechaza el UTF-8 inválido; aquí el único texto inválido es un surrogate suelto, y el error lo cita como Go citaría sus bytes en UTF-8 generalizado.
- `CborEncoder.uint` exige 0..2^53-1, con un texto propio, como en `datekeys-ts`; `uint64` escribe hasta 2^64-1.
- **DER estricto.** Port de `internal/der/der.go` en `601e6d2`, ya del borrador v0.12: `check`, `split`, `content`, `setOfSorted` y `parseTime`. `parseTime` devuelve un `DerTime` con los campos y los segundos Unix, exacto al nanosegundo. Es interno: `lib/datekeys.dart` no lo exporta.
- **Pruebas.** Port de `errors_test.go`, `codec_test.go`, `internal_test.go`, `vectors_test.go` y `der_test.go`, de `cbor.test.ts` y de `bytes.test.ts`, con los textos de error que imprime Go.
- Los objetivos de fuzzing de Go son propiedades con semilla, contra un codificador y un decodificador de referencia escritos aparte, como `internal/cbortest`.
- `testdata/vectors/cbor.json`: los 36 `accept` y los 67 `reject`, con los límites de `walk` y los valores. Los 172 vectores de `schemas` se leen y se aplazan: necesitan los decodificadores de esquema de la etapa 4.
- 169 pruebas en la VM y una aplazada. Las 56 que no leen ficheros pasan también en Node.js (`dart test -p node`); las que leen ficheros llevan `@TestOn('vm')`.
### Etapa 0: el paquete (05-10-2026)
- Paquete `datekeys` en Dart puro, sin Flutter, para Dart 3.13 y sin publicar (`publish_to: none`).
@ -6,11 +6,29 @@ Es la tercera implementación de la especificación, después de la de referenci
## Estado
Está hecha la etapa 0 del plan (`docs/PLAN_dart.md` del espacio de trabajo): el paquete, sus herramientas y `testdata/` sincronizado. Todavía no implementa nada del protocolo. Las etapas siguientes lo traen en este orden:
Están hechas las etapas 0 y 1 del plan (`docs/PLAN_dart.md` del espacio de trabajo):
- la etapa 0, el paquete, sus herramientas y `testdata/` sincronizado;
- la etapa 1, los errores normativos, los bytes, el perfil CBOR del §58 y el DER estricto, también el de los tiempos.
La etapa 1 porta tres ficheros de `datekeys-go` en `601e6d2`, con las mismas lecturas, las mismas comprobaciones en el mismo orden y los mismos textos de error:
| Módulo | Contenido | En Go |
|---|---|---|
| `lib/src/errors.dart` | Los 19 códigos del §69 en su orden (`ErrorCode`), `DateKeysException` con el mensaje `contexto: CÓDIGO`, `wrap`, `withContext` y `errorCode` | `errors.go` |
| `lib/src/bytes.dart` | Hexadecimal, comparación y concatenación; UTF-8 estricto que conserva un U+FEFF inicial; `utf8.DecodeRune` y el `%q` de Go, con la tabla de `strconv.IsPrint` de Go 1.26 | `unicode/utf8`, `strconv` |
| `lib/src/der.dart` | `check`, `split`, `content`, `setOfSorted` y `parseTime`, con UTCTime y GeneralizedTime exactos al nanosegundo. Es interno, como en Go | `internal/der/der.go`, ya del borrador v0.12 |
`lib/datekeys.dart` exporta los errores, el CBOR y las funciones de bytes que necesita quien use la librería.
Los enteros son exactos en la VM y en la web. El `int` de Dart tiene 64 bits con signo en la VM y en la web es un double, exacto hasta 2^53. Por eso la librería no usa un `int` por encima de 2^53-1, ni desplazamientos u operaciones de bits de más de 31 bits:
- un entero de CBOR es un `int` hasta 2^53-1 y un `BigInt` por encima, como el `number | bigint` de `datekeys-ts`;
- `CborDecoder.uint` devuelve un `int`, porque todos los esquemas acotan sus enteros en 2^53-1, y `uint64` devuelve un `BigInt`.
Las etapas siguientes traen el resto del protocolo en este orden:
| Etapa | Contenido |
|---|---|
| 1 | Bytes, errores normativos, CBOR determinista (§58) y DER estricto |
| 4 | Formatos, inspección (pasos 1 a 8) y apertura (pasos 9 a 18) |
@ -51,6 +69,14 @@ tool/check.sh
- `dart test`;
- la copia de `testdata/` frente al repositorio de Go, que debe estar al lado, en `../datekeys-go`.
Las pruebas que no leen ficheros corren también compiladas a JavaScript, en Node.js. Así se comprueba que los enteros son exactos en la web. No forman parte del gate:
```bash
dart test -p node
```
Las que leen ficheros llevan `@TestOn('vm')`.
## Datos de prueba
`testdata/` es una copia de `datekeys-go/testdata` en un commit fijo. `testdata/SOURCE.json` registra el commit y el SHA-256 de cada fichero, igual que en `datekeys-ts`. La copia actual es la del tag `spec-v0.11` (`ae33434`).
