datekeys-doc/spec_v0.9/consistency.md

# Review of the DateKeys v0.9 design: consistency, compatibility and implementability

These checks passed, so the core design holds:
- **Arithmetic.** Every padding and length figure in the note recomputes exactly, and all 5 fixtures fit the length formulas. The v2 control is 103 bytes, and `reforzado(L_MAX+1)` is 2^53.
- **Old readers.** None of the 1825 `inspect_differential.json` cases produces VERSION 2 (byte 4 comes out as a7, 05, e8 or 20). Go `framing.go:111` and TS `framing.ts:47` both reject VERSION 2 at step 2 with no network request.
- **Precedence.** Every existing §69.1 example stays true, and so do the six new rows.
- **Format-1 codes.** No invalid format-1 input changes its code except those with VERSION 2. A control v1 with keys 6/7 gives `ERR_NON_CANONICAL_CBOR` in both readers. A control v2 in format 1 gives `ERR_UNSUPPORTED_VERSION` in both.

Corrections, most serious first:

1. **HIGH: relabel cases that offer a `.dkk` fail at step 9.a, not at 12 or 14.** Every writer-made `.dkk` has a `capsule_digest`, and editing byte 4 breaks it.
   - Evidence:
     - `encrypt.go:232` always sets `Verification{CapsuleDigest}`.
     - `time_and_key_portable.dkk.json` has `capsule_digest 2e97…`.
     - The existing mutation "capsule_digest of the .dkk does not match" (one byte edit) gives `ERR_ACCESS_INVALID`, step 9, `network:false`.
     - The corpus reader gets a seekable file, so the digest is checked (`testdata/README.md:212-214`).
   - Wrong as written:
     - §11 row "format 1 time_and_key relabeled format 2 | time_and_key_portable.dkc + .dkk → ERR_POLICY_STRUCTURE_MISMATCH 12".
     - §11 row "format 2 time_and_key relabeled format 1 | … + .dkk → ERR_UNSUPPORTED_VERSION 14".
   - Unconditional claims that need qualifying: the time_and_key rows of the §1.3 table, the §26 addition ("Antes falla en el paso 12 o en el 14"), the last paragraph of §70, and §76 case 4 ("falla en el paso 14 en los dos lectores").
   - Fix: build these cases with `identities` (the raw `access_material`), not the `.dkk`. In §64 write "…con una identity". Add to §26 and §70: "o en el paso 9.a, con `ERR_ACCESS_INVALID`, si se ofrece una `.dkk` con `capsule_digest` y se comprueba (§43, §69.1 Alcance)".

2. **MEDIUM: "En ningún caso entrega el contenido con su relleno" (§70) and "No path outputs padding as content" (§1.3) claim too much.**
   - For a format-2 `time_only` capsule, anyone can do this after the release:
     1. Open the control with `FK_TIME` and read `I_PAYLOAD`.
     2. Set VERSION to 1.
     3. Seal a v1 control with the same `I_PAYLOAD` and a recomputed `header_binding` (§36.1).
   - Both readers then open it as format 1 and output content‖zeros.
   - Fix: limit the claim to "una cápsula de formato 2 cuyo control no se ha vuelto a sellar", and cite §36.1 and §55.1.

3. **MEDIUM: new normative rules outside D1–D7 that §12 does not list for the author's confirmation.**
   - `L_MAX = 2^53 − 2^46`. It is a new writer MUST NOT and a new reader rejection (`ERR_NON_CANONICAL_CBOR`). D2 only said "up to the format limits", and today `PAYLOAD_AGE` has no bound.
   - The MUST to shuffle the 16 stanzas with a CSPRNG. It is needed for D1: the portable-key holder is last in `encrypt.go:294` and would learn the exact count. The text should also require an unbiased shuffle.
   - "Control schema version MUST equal the format". This ties every future format to a new control version. Better as a format → version table. Also state that a new padding code needs a new format, so old readers still fail at step 2.
   - The §72 clause "salvo que su registro diga otra cosa". It adds a registry declaration that is not in §72's MUST-declare list: either add it to the list or drop the clause.

4. **MEDIUM: writer implementability — L must be known up front, and a streaming writer cannot take back what it wrote.**
   - Go: `Encrypt(dst, src io.Reader, …)` streams a source of unknown length (`encrypt.go:218`), after writing PRELUDE, header and control to `dst` (`207-211`).
   - TS: the phase 3 plan (decision 2) accepts a `ReadableStream`, whose length is unknown.
   - Both APIs need an explicit length input, or must spool the source to a temporary file first. §61.1 and §62.1 rule 6 should say a writer MAY spool and MUST NOT guess L.
   - "abortar y descartar lo escrito" (§61 step 13, rule 9) is something a streaming writer cannot do. Rephrase as: the writer MUST report the error, and whoever receives the output MUST discard it, as with the capsule-rejected case of §56.

5. **LOW-MEDIUM: nothing says a reader must not reserve memory from L.** A control may declare L up to 8.9·10^15. Add to §57 and §63 step 16: "L no es una longitud de trama: un lector no reserva memoria según L; la acota el ciphertext". The TS reader already bounds its buffer by the ciphertext length (`open.ts:422`); the text should keep that.

6. **LOW-MEDIUM: §69.1 paragraph L2106 (cross-object checks) is not updated.** The design moves one cross-object check (control version against PRELUDE VERSION) into layer 2, but L2106 still lists every cross-object check as belonging to its own step. Add "y la versión de `CONTROL_CBOR` frente al formato (paso 14, capa 2)" to that list.

7. **LOW: a proposed `cbor.json` vector cannot test what it claims.** "padding 3 and an unknown critical extension (layer 3 before layer 4)" does not work there: schema vectors never check critical extensions (`testdata/README.md:115-118, 131-133`). Keep it only as a mutation or a `TestPrecedenceAcrossSteps` case at step 14.

8. **LOW: the informative note of §62.1 is wrong.** It says "Con C = 91 y k = 1 o 3, las fórmulas dan las longitudes de los cinco fixtures". But `time_only_extensions` has C = 127 (482 = 335 + 4 + 127 + 16), and three of the fixtures are `time_only`, with no k. Fix: "C = 91 (127 en time_only_extensions); k = 1 o 3 en los dos time_and_key".

9. **LOW: the floating-point log2 example is outside the valid range.** 2^53 − 1 is above L_MAX. Use L = 2^49 − 1, the first failing case in range: `Math.log2` gives 49 and the correct value is 48 (checked in Node).

10. **LOW: "bloque256 añade menos de 256 bytes" is false for L = 0**, which adds 256. Write "como mucho 256".

11. **LOW: new §39 says "En formato 1, INNER_ACCESS_AGE MAY contener uno o más stanzas".** That weakens the MUST (≥ 1) of §33 and §36. Write "contiene (MUST, §33) uno o más".

12. **LOW: §74 contradicts itself and the README.**
    - The design declares the encoding of L and the 16 slots "no provisionales". §74 still lists "schema CBOR final byte-a-byte de CONTROL_CBOR" as open, and spec/README says v0.9 is "not frozen".
    - The out-of-scope list sits under "Aspectos todavía provisionales". Put it in its own "Trabajo futuro" paragraph.

13. **LOW: forward references.** §29.1 cites `testdata/vectors/padding.json`, which does not exist. §76 cites "TODO" tests. Every existing §76 entry cites only tests that exist. Mark these "a generar con la implementación de v0.9", or keep the test list out of §76 until they exist.

14. **LOW: wording in §55.2.**
    - The ".dkk lleva en claro …" line leaves out the credential itself (`access_material`).
    - "Credencial" in §39 means a recipient (a public key). In §63 step 9 it means an identity or `.dkk` the reader offers. Define the term once.

15. **INFO: effects on the TS phase 3 plan (`App/docs/PLAN_fase3_escritura.md`).**
    - Decision 6 keeps `R_ACCESS` last; it must become the shuffle.
    - The test "1 024 recipients + portable" becomes a rejection above 16.
    - Decision 8 ("no vuelve a descifrar") and plan §6, which wipes `I_PAYLOAD` right after the real seal, conflict with the new SHOULD self-check that `I_PAYLOAD` opens the `PAYLOAD_AGE` header. Wipe it after that check.

16. **INFO: test data.**
    - The `cbor.json` vector "unknown key 6" (control, key 6 = uint 0) has a misleading name once key 6 exists; rename it.
    - Go's `Open` never records a step 17 stage (`open.go:246` goes to `261`), so fixture `stages` lack step 17. The new step 17 checks make that entry worth adding for §67.