You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
64 lines
7.3 KiB
64 lines
7.3 KiB
# PROPOSAL: normative language and precedence of sources
|
|
|
|
**Status: PROPOSAL for the author to decide. Nothing here is in force. The specification has not been edited.**
|
|
|
|
The completeness review of v0.13 (step 3) asks, before an external review, to declare which language is normative and to set precedence between the text, the CDDL and `testdata/README.md`. Today the specification says neither.
|
|
|
|
## 1. What the sources say today
|
|
|
|
- **Specification text** (`DateKeys_Protocol_Specification_v0.14.md`, Spanish). It uses RFC 2119 keywords in English with Spanish equivalents (§2). It does not say which language is normative or what wins when sources disagree.
|
|
- **CDDL** (`spec/datekeys.cddl`). Its header calls itself the «Normative companion» of the specification. The text delegates to it: «cualquier violación de una regla normativa de `datekeys.cddl` … → `ERR_NON_CANONICAL_CBOR`» (§57), and layer 3 of §69.1 checks «toda regla normativa de `datekeys.cddl`». Some CDDL rules are marked as non-normative implementation limits of the reference (§74). Its header comment is stale: it names v0.11 and says the reference implements v0.9.
|
|
- **Test data** (`testdata/`, `testdata/README.md`). The README says: «The rules that decide each verdict are in the specification; this file points to them». §16 says the definitive vectors MUST be generated from the reference implementation and frozen before v1.0. §76 lists a fixture, a mutation test and the CDDL among the sources of a reproducible case.
|
|
- **Reference implementation** (Go). §16 and §67 make it the generator of the vectors. The v0.8.2 refinements of §76 record cases where the reference and `testdata/README.md` held rules that the text did not, and the text was then changed to match.
|
|
|
|
So in practice, until now, a gap between sources was closed by writing the rule into the text. No rule says what an implementer should follow while a gap exists.
|
|
|
|
## 2. Proposed rules
|
|
|
|
1. **Language.** The Spanish text of the specification is the only normative text. Any English version, including this package and a future translation, is informative. If an English text disagrees with the Spanish one, the Spanish one decides, and the difference is an error of the English text.
|
|
2. **Precedence.** When two sources disagree about the same rule, the order is:
|
|
1. the specification text;
|
|
2. `datekeys.cddl`;
|
|
3. the test vectors and fixtures of `testdata/`, with `testdata/README.md`;
|
|
4. the reference implementation, then the other implementations, as §16 and §67 already put the reference first.
|
|
3. **Delegation is not disagreement.** A normative rule of the CDDL that the text does not state, and does not contradict, is normative, as §57 and §69.1 already say. Rules the CDDL marks as implementation limits stay non-normative (§74). Precedence applies only when two sources say different things.
|
|
4. **A disagreement is a defect.** Any disagreement found between the sources is a defect: the text decides. It is recorded in the project's working notes (`docs/HANDOFF.md`) and fixed in the next version, with its reproducible case in §76. Until then the vectors and fixtures are not touched: the gates regenerate `testdata/` from the reference and fail on any change, and the TypeScript guard fails on a file that no test runs.
|
|
5. **Reviews are labelled by who did them.** §76 names each review with its kind: internal and AI-assisted, or external and human, with the reviewer's name, scope and date for an external one (§75 item 10).
|
|
|
|
## 3. Spec text changes this would need (next version, v0.15 or later)
|
|
|
|
The v0.14 text is tagged and does not change. These changes would go into the next version, each recorded in its §76 block:
|
|
|
|
1. **A new paragraph on language and precedence, at the end of §1** (decided by the author on 6 October 2026: not a §0, which would shift the numbering every document cites). Draft wording in Spanish (the normative language), for the author to edit:
|
|
|
|
> El texto normativo es esta especificación en español. Toda traducción es informativa: si una traducción y este texto difieren, decide este texto. Si este texto, `datekeys.cddl`, los vectores y fixtures de `testdata/` y la implementación de referencia difieren sobre una misma regla, decide, en este orden: este texto, `datekeys.cddl`, `testdata/` con `testdata/README.md`, y la implementación de referencia. Una regla normativa de `datekeys.cddl` que este texto no contradice es normativa (§57, §69.1); los límites de implementación que marca no lo son (§74). Toda discrepancia es un defecto, que se corrige con un cambio registrado en §76.
|
|
|
|
2. **§2 Terminología.** Optionally state that the English keywords are the normative ones and the Spanish equivalents follow them.
|
|
3. **§76, labels of past reviews.** Replace the wording that suggests external or human review:
|
|
- «Correcciones de la revisión formal» and «Proceden de la revisión formal e independiente de esta especificación, una de las fuentes que admite esta política («revisión criptográfica o técnica externa»)» (v0.8.2 block): say that it was an internal review assisted by AI, done in the working sessions, and that it is not the external review of §75 item 10;
|
|
- «El diseño pasó una revisión de seguridad externa y dos revisiones adversariales» (v0.10 block): say that the security review was by Fable, an AI system;
|
|
- «la revisión cruzada de Fable y Astra» (v0.11 block): say that Fable and Astra are AI systems;
|
|
- «tres revisiones independientes» (v0.11 change 8): say that they were AI-assisted reviews;
|
|
- «segunda implementación independiente» (v0.8.2 refinements and amendment): say that the TypeScript implementation was written with the reference code in view.
|
|
4. **§76, list of sources.** Add «revisión interna asistida por IA» as its own source, separate from «revisión criptográfica o técnica externa».
|
|
5. **§75 item 10.** Say that the external review is recorded in §76 with the reviewer's name, scope and date.
|
|
6. **Header, line 8.** «Implementación de referencia prevista: Go» → the reference implementation exists (`datekeys-go`).
|
|
7. **§16 and §67.** Align with rule 4: the vectors come from the reference, but the text decides; a vector that contradicts the text is a defect.
|
|
8. **§59.** Optionally add that a published English translation is informative and carries the SHA-256 of the Spanish version it translates.
|
|
|
|
## 4. Changes outside the spec text
|
|
|
|
Not normative; they can be done in the repositories at any time, and the external reviewer will see them first:
|
|
|
|
- `spec/datekeys.cddl`, header comment: the current version, and a line pointing to the precedence rule.
|
|
- `testdata/README.md`: one line stating the precedence rule.
|
|
- `spec/README.md`: one line stating that the Spanish text is normative.
|
|
- `docs/traceability.md` and `README.md` of `datekeys-go`: brought up to v0.14 at `22f184c` (`artifacts.md` section 5).
|
|
|
|
## 5. Decided by the author (6 October 2026)
|
|
|
|
- The proposal is approved, with a paragraph at the end of §1 and rule 4 as written above.
|
|
- Among implementations, the reference first.
|
|
- Whether English becomes normative is left for v1.0.
|
|
- These text changes do not open a version now: they go into the version that records the findings of the external review, together with the labels of §76 and the record of the review (§75 item 10). The cover letter already states that every prior review was by AI.
|