DAW/daw-contracts

Fork 0

Define deterministic source_hash computation for daw_i18n/v1 #6

New issue

Closed

opened 2026-08-14 14:20:09 +02:00 by michael · 1 comment

michael commented

2026-08-14 14:20:09 +02:00

Owner

Problem

daw_i18n/v1 requires every translation resource to carry a
source_hash computed over the canonical resource's
(text, context, parameters).

The contract currently does not define either:

the canonical byte representation of these fields, or
the hash algorithm.

As a result, independent conforming implementations can produce
different source_hash values for the same canonical resource.

This was discovered while implementing the first real
daw_i18n/v1 resources in DAW/daw-lua-common.

Proposed definition

Define source_hash as SHA-256 over a canonical JSON representation
containing exactly:

text
context
parameters

Rules:

Missing context is represented as JSON null.
Missing parameters is represented as JSON null.
Object keys are sorted lexicographically, recursively.
JSON is encoded as UTF-8.
No insignificant whitespace is emitted.
SHA-256 is computed over the resulting UTF-8 byte sequence.
source_hash is represented as 64 lowercase hexadecimal characters.

Example canonical hash input:

{"context":null,"parameters":null,"text":"Invalid Base64 character"}

The hash is intended only for translation-staleness detection, not
for security.

Scope

Update the normative daw_i18n/v1 specification and contract
descriptor.

No change to resource identity, translation semantics, fallback
policy, or rendering behavior is intended.

Acceptance criteria

daw_i18n/v1 normatively defines the canonical hash input.
SHA-256 is normatively specified as the hash algorithm.
UTF-8 encoding and lowercase hexadecimal output are specified.
Missing optional fields have an unambiguous representation.
Object key ordering is deterministic, including parameters.
Independent implementations can calculate identical
source_hash values for the same canonical resource.
At least one test vector with expected source_hash is included.

DAW/daw-lua-common#48

## Problem `daw_i18n/v1` requires every translation resource to carry a `source_hash` computed over the canonical resource's `(text, context, parameters)`. The contract currently does not define either: - the canonical byte representation of these fields, or - the hash algorithm. As a result, independent conforming implementations can produce different `source_hash` values for the same canonical resource. This was discovered while implementing the first real `daw_i18n/v1` resources in `DAW/daw-lua-common`. ## Proposed definition Define `source_hash` as SHA-256 over a canonical JSON representation containing exactly: - `text` - `context` - `parameters` Rules: - Missing `context` is represented as JSON `null`. - Missing `parameters` is represented as JSON `null`. - Object keys are sorted lexicographically, recursively. - JSON is encoded as UTF-8. - No insignificant whitespace is emitted. - SHA-256 is computed over the resulting UTF-8 byte sequence. - `source_hash` is represented as 64 lowercase hexadecimal characters. Example canonical hash input: ```json {"context":null,"parameters":null,"text":"Invalid Base64 character"} ``` The hash is intended only for translation-staleness detection, not for security. ## Scope Update the normative `daw_i18n/v1` specification and contract descriptor. No change to resource identity, translation semantics, fallback policy, or rendering behavior is intended. ## Acceptance criteria - [ ] `daw_i18n/v1` normatively defines the canonical hash input. - [ ] SHA-256 is normatively specified as the hash algorithm. - [ ] UTF-8 encoding and lowercase hexadecimal output are specified. - [ ] Missing optional fields have an unambiguous representation. - [ ] Object key ordering is deterministic, including `parameters`. - [ ] Independent implementations can calculate identical `source_hash` values for the same canonical resource. - [ ] At least one test vector with expected `source_hash` is included. ## Related - `DAW/daw-lua-common#48`

michael added the

coordination/cross-repo

labels

2026-08-14 14:20:09 +02:00

michael referenced this issue from a commit

2026-08-14 16:22:16 +02:00

feat(daw_i18n, daw_error): specify source_hash algorithm, resource_id context recommendation, and parameter-to-data binding

michael commented

2026-08-14 16:22:57 +02:00

Author

Owner

Implemented

daw_i18n/v1/specification.md Section 6.1 and contract.json now
normatively define source_hash: SHA-256 over canonical JSON
{text, context, parameters}, with explicit byte-level string
serialization rules (raw UTF-8, no \uXXXX escapes, fixed control-char
escaping, no normalization) after an additional review round found
that 'canonical JSON' alone was still serializer-ambiguous for
non-ASCII text.

Three test vectors included (plain ASCII, with parameters, with
non-ASCII text/context), all independently verified.

## Implemented daw_i18n/v1/specification.md Section 6.1 and contract.json now normatively define source_hash: SHA-256 over canonical JSON {text, context, parameters}, with explicit byte-level string serialization rules (raw UTF-8, no \uXXXX escapes, fixed control-char escaping, no normalization) after an additional review round found that 'canonical JSON' alone was still serializer-ambiguous for non-ASCII text. Three test vectors included (plain ASCII, with parameters, with non-ASCII text/context), all independently verified.

michael closed this issue

2026-08-14 16:22:59 +02:00

michael referenced this issue from a commit

2026-08-16 05:49:57 +02:00

feat(i18n): add daw_i18n/v1 resources for base64 and config_parser

michael referenced this issue from a commit

2026-08-16 08:11:02 +02:00

feat(i18n): add resource_id to all bootstrap error sites

michael referenced this issue from a commit

2026-08-16 08:52:04 +02:00

fix(decimal): validate int/scale integrality in is_decimal()

michael referenced this issue from a commit