spec: parent_record_hash's preimage is stated only in a document that binds nothing

[chernistry]

delegation.parent_record_hash is the field a verifier walks to reconstruct a delegation chain, and nothing normative says what it is a digest of.

At e7e2eca:

• The schema gives it a format and a sentence: "pattern": "^sha(256:[0-9a-f]{64}|384:[0-9a-f]{96})$", described as "SHA-256 or SHA-384 digest of the parent hop's Trust Record."
• spec/trace-v0.2.md does not mention the field at all (zero occurrences).
• docs/rfcs/a2a-delegation-profile.md §4.1 does state a preimage, and D-3 (parent_not_found) is defined in terms of it — but that document says "Status: Draft proposal. Binds nothing."

"the parent hop's Trust Record" has at least three natural readings, and they give different digests:

1. The published file's bytes.
2. RFC 8785 (JCS) over the complete record, signature included.
3. RFC 8785 over the record with signature removed — the same body the signature itself covers.

I computed all three against our own delegated-parent record. Readings 1 and 2 agree on it and match the child's link; reading 3 gives a different digest. So two implementers reading only the schema can both act in good faith and produce chains that resolve to dangling links against each other, with no diagnostic on either side saying why.

The complete-record reading is the right one, and it should be normative

§4.1 already takes it, for a reason worth promoting out of a draft: a digest over the signed body alone commits to what the parent said and not to who said it, so any holder of any key can re-sign bytes that satisfy the same link. That is the difference between a chain that binds hops and one that binds statements.

Asking for that sentence to move somewhere that binds — the schema description, or spec/trace-v0.2.md — rather than for a new rule.

One reading is a trap rather than a disagreement

Plain json.dumps(obj, sort_keys=True, separators=(",", ":")) over the complete record produces the same digest as JCS on records like ours, so an implementer who reaches for it interoperates and has no reason to look further.

It stops matching the first time a record carries a non-ASCII character, and the cause is a default rather than a choice: json.dumps escapes non-ASCII to \uXXXX unless ensure_ascii=False is passed. Putting 模型-π in model.model_id and v1-é in policy.version, both of which the schema accepts:

JCS                              91eca6bbe63ebe2ffeba09c0...
json.dumps (default)             fd74a7636b2665d69185150c...   diverges
json.dumps (ensure_ascii=False)  91eca6bbe63ebe2ffeba09c0...   agrees

A silent agreement that ends on a field nobody thought was load-bearing is worse than a mismatch on day one. If the normative text names RFC 8785 explicitly rather than "canonical JSON", that whole class goes away.

Why this surfaced here

We publish a delegated parent/child vector pair whose link is built to the complete-record reading, and the aggregate over them carries member digests under the same convention. When an independent implementer re-derived the link, the preimage had to be inferred from our vectors rather than read from the specification — which works exactly once, for whoever has our vectors in front of them.

Same shape as #232, #240 and #244: a rule an implementer needs, that no binding surface states.

Credit: @lywinged enumerated six encodings against our parent record and isolated both the four-way split and the json.dumps trap.

[lywinged]

Agreed on the ask, and the RFC 8785 point at the end is the part I would keep front and centre. One measurement in the body comes out differently for me, and it happens to strengthen the argument.

Readings 1 and 2 come apart for me rather than agreeing, by one byte, a trailing newline. That makes it three digests rather than two. Against delegated-parent-trust-record.json at db38631:

child's link             sha256:61dc2465e0435c251d0b334ef0e77a2c349d1d789aa83cc4c225cca1f2408c57
1 published file bytes   sha256:5d1cac9d1a5e187353567633a03d4cee34ebd44237ac63f317cd9dd7ae94643a  differs
2 JCS, complete record   sha256:61dc2465e0435c251d0b334ef0e77a2c349d1d789aa83cc4c225cca1f2408c57  matches
3 JCS, signature removed sha256:0595067b7bb82aea4e723cbe1822531a7d6c6a26b1314152f58dc3beb8b0ce7c  differs

The relationship is the same across all four vectors. Each file is the JCS encoding plus one 0x0a:

vector	file	JCS	last byte
single-execution	1328	1327	0a
delegated-parent	1148	1147	0a
delegated-child	1329	1328	0a
aggregate	1627	1626	0a

It also reaches three published links rather than one, since the aggregate's two references[].digest values are digests of the parent and child under the same convention.

Reading 1 is a worse case than the other two

Readings 2 and 3 are a disagreement: two digests, each with an argument behind it, and your §4.1 reasoning settles which one. Reading 1 is not that. As far as I can find, no file in the repository has bytes that hash to 61dc2465...: the preimage only exists in memory at generation time, and the newline goes on during the write. So the "works exactly once, for whoever has our vectors in front of them" fallback may be narrower than it looks, since it also asks the reader to guess that the file's last byte is not part of the record.

Which I think helps the ask rather than complicating it. §4.1 already says "Over the RFC 8785 encoding of the complete record", and RFC 8785 output carries no trailing newline, so reading 1 is not a third interpretation of the spec at all. It is an artifact of publishing the canonical form as a file, which only a corpus author ever does. Moving that sentence to a surface that binds, with RFC 8785 named rather than "canonical JSON", closes reading 1 and reading 3 together.

The rule is written down, in a place that cannot carry it

I went looking for the statement before assuming there wasn't one, and you have it, stated exactly right:

with no re-canonicalisation and no trailing newline. The committed file carries one trailing newline for POSIX friendliness

That is a test docstring. Every test that hashes a vector applies the correction first, so the suite carries that knowledge even though no published document states it, and the vectors' README does not mention the preimage.

Which might be worth putting in the issue rather than leaving out of it, since it is your own point in a stronger form: the rule was not overlooked, it was worked out and written down correctly, and the place it lives still cannot deliver it to a reader.

Suggestion, take it or leave it: list reading 1 as its own row rather than folding it into reading 2. It is the one an implementer reaches by doing the obvious thing to a file.

[imran-siddique]

Confirmed at 25013c59d607860a4a4d2608476280286f688243: parent_record_hash occurs zero times in spec/trace-v0.2.md and six times in docs/rfcs/a2a-delegation-profile.md, which opens with "Status: Draft proposal. Binds nothing." So the only statement of the preimage for the field a verifier walks to rebuild a delegation chain lives in a document that disclaims being normative. That is a real defect and computing all three readings against your own record before reporting it is what makes it actionable rather than a question.

Ruling: reading 2. RFC 8785 (JCS) over the complete record, signature included. It becomes normative in the spec, not in the profile.

Your argument for the complete record is the right one and I want it kept in the text: a digest over the signed body alone commits to what the parent said and not to who said it, so a chain built on it can be reassembled from a differently-signed parent that says the same thing. The link has to bind the identity, not just the content.

One refinement, because your evidence understates the risk. You found readings 1 and 2 agreeing on your record and concluded they are interchangeable in practice. They are not. Reading 1 is the published file's bytes, which are whatever the producer happened to write: key order, whitespace, trailing newline, encoding. Reading 2 is canonical by construction. They coincided on your record because your producer already emits JCS-ordered bytes. A producer that pretty-prints, or that emits keys in insertion order, breaks reading 1 while reading 2 is unaffected.

So the normative text has to name JCS specifically rather than saying "the parent record's bytes", or we replace a three-way ambiguity with a two-way one that fails only for the producers least likely to notice.

To be concrete about what I will write:

• parent_record_hash is the digest, in the algorithm named by its own prefix, of the RFC 8785 canonical serialization of the complete parent Trust Record including its signature field.
• It is not the digest of the parent's published bytes, and it is not the digest of the signature pre-image.
• The two are stated as explicit non-normative notes, because both are the mistake a careful implementer makes.

On where this lands. Normative text from an individual would normally sit under our organisational-sponsor rule, and I want to be clear this is not being held by it: you have identified a defect in existing normative coverage rather than proposing a new obligation, and correcting that is a maintainer's job. I will carry the spec change. Your D-3 (parent_not_found) reasoning from §4.1 carries over unchanged.

The wider pattern

Fourth report in three days, with #232, #240 and #244, all of the same shape: the normative spec, the schema, the reference model and the docs state different things and nothing says which wins. I have opened a tracking issue for the precedence question rather than treating each as local, linked below. This one is the sharpest instance because the normative surface says nothing at all, so there is not even a conflict to adjudicate, just a hole with a draft in front of it.

[imran-siddique]

Tracking the pattern this belongs to in #247: the normative spec, the JSON Schema, the reference model and the docs state the rules and nothing says which wins. This issue is one of five instances found in three days. The ruling above stands on its own; #247 is about stopping the next one.

[chernistry]

Ruling implemented, and the three readings reproduce exactly here.

Our emitter now computes the delegation link as SHA-256 over the RFC 8785 canonical form of the parsed, complete signed parent record — signature included, reading 2. Aggregate member references use the same preimage. That is on main and ships in our next release.

Running our own canonicalisation over the published delegated-parent-trust-record.json reproduces @lywinged's numbers byte for byte:

file bytes            sha256:5d1cac9d1a5e187353567633a03d4cee34ebd44237ac63f317cd9dd7ae94643a
JCS, complete record  sha256:61dc2465e0435c251d0b334ef0e77a2c349d1d789aa83cc4c225cca1f2408c57
JCS, signature removed sha256:0595067b7bb82aea4e723cbe1822531a7d6c6a26b1314152f58dc3beb8b0ce7c
child's link          sha256:61dc2465e0435c251d0b334ef0e77a2c349d1d789aa83cc4c225cca1f2408c57

1148 file bytes, 1147 JCS bytes, last byte 0a — the trailing-newline relationship holds across the vectors we carry.

One thing worth putting in the normative text, from having shipped the wrong version of it. Our producer previously hashed the emitted JSON string bytes rather than the JCS form of the parsed document. For ASCII-only records the two coincide, so it passed every vector and every round-trip we had. It took a non-ASCII field — a unicode model identifier — to make the digests diverge from what an RFC 8785 verifier computes.

That is the practical danger of the preimage living only in a document that binds nothing: an implementation can be accidentally conformant on the published vectors and wrong on the first record a user writes in their own language. If the spec adds a vector whose fields are deliberately non-ASCII, the two readings separate and a producer cannot pass by coincidence. Happy to contribute such a vector as a PR if that is wanted.

[lywinged]

@chernistry Yes, wanted. Byte for byte reproduction from a second implementation is what these vectors exist
to enable, and a vector born from having shipped the wrong preimage is worth more than one
designed at a desk.

Two additions would make it close the whole class, both measured before writing this:

• carry the non-ASCII content in a literal and an escaped spelling across the corpus, since
  "café" and "caf\u00e9" hash apart as string bytes and together under JCS of the parsed
  record, which is exactly the coincidence your producer shipped;
• put one supplementary-plane character in a key name. RFC 8785 orders properties by UTF-16 code
  units, so U+1F600 sorts before U+FFFD there and after it in raw UTF-8 byte order. A producer
  that sorts keys by encoded bytes passes every BMP-only vector and fails only this one.

Follow the generator pattern beside the existing sets, deterministic keys and a script that
rewrites its fixtures in place, and tests/test_generators_reproduce_fixtures.py picks it up
automatically. Conformance vectors need no sponsor.

Tool-assisted: the two measurements and this note.

[chernistry]

Both in.

Checked the ordering claim before agreeing to it, and it reaches one step further than UTF-8 byte order:

U+1F600 vs U+FFFD
UTF-16 code units    d83dde00 < fffd      -> U+1F600 first   (JCS)
UTF-8 bytes          f09f9880 > efbfbd    -> U+FFFD  first
Unicode code points  1F600    > FFFD      -> U+FFFD  first

That third row is json.dumps(..., sort_keys=True). Python orders keys by code point, so it agrees with JCS on every BMP-only key and diverges the first time an astral key is compared against one in U+E000-U+FFFF — astral keys sort as their high surrogate, below U+E000, in UTF-16 and above U+FFFF in code point order.

It is the same shortcut whose escaping half you isolated: ensure_ascii=False corrects the escaping and leaves the ordering wrong, which is the worse of the two states, because it now looks corrected and passes every BMP-only vector. The key-name case is the one that separates them.

Literal and escaped confirmed too — café and café differ as file bytes and agree under JCS of the parsed record. Both spellings go in the corpus.

Building it as a generator beside the existing sets: deterministic keys, fixtures rewritten in place, so tests/test_generators_reproduce_fixtures.py picks it up. PR to follow.

[chernistry]

Posting the preimage from a shipped implementation, since that is what this issue says it is missing.

The rule, as implemented:

delegation.parent_record_hash = "sha256:" + hex(SHA-256(JCS(parent_record)))

where parent_record is the complete parent record as published, including its signature member, and JCS is RFC 8785. No field is removed, blanked or reordered by hand; JCS does the ordering.

Verified across two hops against committed vectors (tests/fixtures/trust-record-vectors/), a three-hop delegation chain signed once and checked in:

link	recomputed sha256:hex(SHA-256(JCS(parent)))	value in the child's delegation.parent_record_hash
parent → child	sha256:61dc2465e0435c251d0b334ef0e77a2c349d1d789aa83cc4c225cca1f2408c57	same
child → grandchild	sha256:d231119fde81369c160e5ef8c16b80a3691d36f6705f8bc1cda80b91aa50ca81	same

Reproducing it is four lines against any RFC 8785 implementation:

import hashlib, json
canonical = jcs_canonicalize(json.loads(parent_record_text))   # RFC 8785, UTF-8 bytes
print("sha256:" + hashlib.sha256(canonical).hexdigest())

Three things the wording has to settle, each of which we hit while building it:

1. The signature is inside the preimage. The parent's signature is a member of the object being hashed, unlike the record's own signature preimage, where §"canonical JSON form of the record with only this field absent" removes it. Two different canonicalisations of the same record, one field apart, and nothing normative currently says which one parent_record_hash uses. That is the single sentence this issue most needs.

2. JCS, not the producer's serialisation. JCS orders by UTF-16 code unit. json.dumps(sort_keys=True) orders by code point, and the two disagree for any key in U+E000–U+FFFF against an astral key — so a record with non-ASCII keys hashes differently under the two, silently, and only for some inputs. We pin that case with a dedicated vector (test_child_delegation_non_ascii_parent_record_hash_matches_jcs_and_diverges_from_raw_bytes); a producer who reads "canonical JSON" and reaches for sort_keys=True gets a chain that verifies on ASCII and breaks on a Cyrillic tool name. Worth naming RFC 8785 explicitly rather than "canonical form".

3. A root hop carries no delegation member at all — not null, not an empty object. The vector above has delegation absent on the parent and present on the other two.

The sha256: prefix is carried in the field value, so the member is self-describing if the digest algorithm ever moves.

Happy to send this as spec text against whichever section you want it in — say the word and name the section, same as #247.