docs(trust-levels): all-zero measurement means no commitment, not software-only

[rajnisht7]

What this changes

Closes #240.

runtime.measurement is required on every record. Under software-only, all-zero was being treated as the default value but both shipped reference adapters (TraceSandboxAdapter, TraceAGTAdapter) deliberately emit non-zero, documented measurements under software-only, so that reading would make the reference implementation non-conformant.

• docs/trust-levels.md: states runtime.measurement is required on every record; under software-only it's a documented software commitment (preimage MUST be documented by the producing profile); all-zero is reserved for producers with no commitment to offer.

Type of change

• Editorial (typo, link fix, clarification: no normative effect)
• Non-breaking spec change (new optional field, new platform profile, informative addition)
• Breaking spec change (requires 14-day comment period and Project Lead sign-off)
• Schema change
• Example addition

Spec section

None

Checklist

• DCO sign-off on all commits (git commit -s)
• CHANGELOG.md updated (for any normative change)
• Breaking changes marked with <!-- CHANGED: #NNN: description --> in spec text
• Backward compatibility statement included (for breaking changes)

[Yatsuiii]

I don't think this can be treated as editorial as written.

The released v0.9.0 reference implementation intentionally emits non-zero runtime.measurement values with runtime.platform: "software-only":

• TraceAGTAdapter sets the platform to software-only and uses sha256(merkle_chain_tip).
• TraceSandboxAdapter defines the unattested measurement as sha256(image_digest + "\n" + bundle_hash) and emits it under software-only.
• The released tests pin both behaviors: AGT chain-tip measurement and sandbox image/policy binding.

That contradicts the changelog statement that existing software-only records already use the all-zero value. The proposed prose would declare released first-party producer output incorrect, while the unchanged schema/model would continue accepting it, creating a new documentation/validation disagreement.

The underlying question appears to be what runtime.measurement means when there is no hardware root:

1. If software-only profiles may carry profile-defined software commitments, their preimage semantics need to be identifiable and documented.
2. If the field is reserved as an all-zero no-hardware sentinel, the adapters need a migration path and somewhere else to carry their current commitments; that is not an editorial-only change.

I think this PR should pause and #240 should be re-scoped around that semantic choice before the all-zero rule is stated as universal.

[imran-siddique]

The substance is right and I want it: runtime.measurement is required on every record, and the all-zero value for software-only was only stated in prose as covering development records. A production software-only producer, origin.kind: self with no hardware root of trust, has to write something too, and today that is inferable from an example block rather than stated. Closing #240 with a rule instead of an example is the correct fix.

It conflicts, and that is my doing rather than yours. I merged several trace-spec PRs today, including #248, #250, #243 and #237, and this branch predates them.

Rebase onto origin/main (currently 0d4b82aa2b8d) and push. Given the size of your change, +5/-3, I would expect the conflict to be adjacent-line rather than substantive: if CHANGELOG.md is involved, keep both entries, and if docs/trust-levels.md is involved, keep your wording, since nothing merged today edits that rule.

I will merge on the green. Nothing about the change itself needs revisiting.

[rajnisht7]

@imran-siddique thank you for the review, have resolved the conflicts

[imran-siddique]

@rajnisht7 the rebase is clean and I said I would merge on the green. I am going back on that, and the reason is in the thread rather than in your diff.

@Yatsuiii is right and I did not answer them. I checked the v0.9.0 source rather than the links, and both shipped first-party adapters emit a non-zero runtime.measurement under software-only, deliberately. TraceAGTAdapter sets platform="software-only" and takes SHA-256 of the merkle chain tip. TraceSandboxAdapter derives its measurement from the image digest and bundle hash, and its module docstring goes further: it explicitly rejects an attestation that names software-only, on the grounds that "an attestation that attests nothing is a contradiction", while intending exactly the software-only-plus-derived-measurement shape this PR would forbid. The released tests pin both.

So the rule as written would declare our own reference implementation non-conformant while the schema kept accepting its output, and the changelog sentence saying existing software-only records already use the all-zero value is not accurate.

The gap you are closing in #240 is real. The rule statement is the part that is wrong.

Here is the ruling, so you have something concrete to rewrite against.

runtime.measurement all-zero means no commitment was made. It does not mean software-only. Those are two different facts and the current prose collapses them.

A software-only record has no hardware root of trust. That is a statement about what backs the measurement, not about whether a measurement exists. A sandbox that hashes its image digest and bundle hash has made a genuine, checkable claim about what ran; it simply has nothing but its own word behind it. Forcing that to all-zero throws away real evidence and gains nothing, because the absence of a hardware root is already stated by platform: "software-only" itself.

All-zero is the correct value in exactly one case: the producer has no commitment to offer at all. That is the same distinction I ruled on in cmcp#596 earlier today. A verifier must be able to tell "this was measured, without hardware backing" apart from "this was never measured". A single sentinel serving both makes that impossible, and the second silently inherits the credibility of the first.

What I would like in the rewrite:

1. State that runtime.measurement is required on every record, which was your original and correct point.
2. State that under software-only the value is a software commitment whose preimage MUST be documented by the producing profile, and that all-zero is reserved for a producer making no commitment.
3. Drop the changelog sentence about existing records already using all-zero.
4. Leave the schema alone. Once the rule reads this way there is nothing for the schema to narrow, and the released adapters stay conformant.

That keeps #240 closed by a rule rather than an example, which was the right instinct.

@Yatsuiii thank you for the citations. Naming the two adapters and the pinning tests is what made this checkable in five minutes instead of being an argument about intent. Your point 1 is the branch I have taken.

[lywinged]

The rule sentence in da33a81 lands the ruling in this thread. It states the field is required on every record, makes the software-only value a software commitment with a documented preimage, reserves all-zero for a producer with no commitment, and reverts the PR's own edit to both schema copies, so the head carries them identical to main. I checked the two preimages the sentence names against the adapters on main: the sandbox one is software_measurement(image_digest, bundle_hash) and the AGT one is SHA-256 over the merkle chain tip, so the examples describe what the reference implementation actually emits. Both are also written down in docs/integration/sandbox-runtime.md and docs/integration/agt.md, so the sentence's documentation requirement is already met by both producers.

One thing is left before this merges, and it is a leftover of the mid-PR reversal rather than a new problem. The CHANGELOG entry was written for the first version and still describes it: it says the doc "now states that the all-zero measurement value covers production software-only records", which is the rule the ruling reversed; it says the schema description "gets the same clarification", while a diff of this head against main at 5c69dc1 shows no change under schema/ or src/agentrust_trace/schema/; and it keeps "existing records already use the all-zero value under software-only", the sentence the ruling asked to drop. The title and body still carry the first version too, and merges here are squashes that take the PR title as the commit subject, so it is worth changing both with the entry.

When you touch the commits, a sign-off on the three that lack one (4d6749e, bd5f944, c79a810) clears the CONTRIBUTING gate at the same time.

One thing for the maintainers rather than for this diff: the schema description of runtime.measurement still reads "Hardware measurement of the workload", and docs/schema.md calls it a "Hardware measurement hash", both now narrower than the rule for software-only. The ruling said to leave the schema alone and did not mention docs/schema.md, so that is a #247 item unless they want the docs page brought in line here.

With the entry and title rewritten to the new rule, this is the one-sentence docs change it set out to be, and the sentence is right.

[lywinged]

The entry now states the ruling above and the title matches it. Two things remain before I approve.

The sandbox preimage in the entry reads sha256(image_digest + bundle_hash). The code (TraceSandboxAdapter.software_measurement) and docs/integration/sandbox-runtime.md line 90 both have sha256(image_digest + "\n" + bundle_hash), so a verifier working from the entry computes a different digest. Add the "\n" to the entry; a grep of 053a47f finds no other copy without it.

Sign-offs: 4d6749e, bd5f944 and c79a810 are still unsigned, and 053a47f is a fourth unsigned one. CONTRIBUTING says a PR without sign-off is not merged, and nothing under .github/workflows/ checks it, so it falls to review. A plain git rebase --signoff re-conflicts on CHANGELOG.md at 18c75cb, I tried it. The clean path is one signed commit: make the "\n" edit first, then soft-reset to 5c69dc1, the merge-base with agentrust-io/main (which has since moved to fc38496), then git commit -s. The result is this diff plus the "\n" fix, two files, CHANGELOG.md and docs/trust-levels.md, and it merges clean against fc38496 as is, no rebase needed; CI re-runs on the push.

One nit, not blocking and no separate push: the body ticks all five boxes under Type of change. Breaking and Schema change are both wrong for this diff, and one box is enough.

CI on 053a47f passes for me locally with the four steps in ci.yml: ruff, the dash check, mypy, and pytest at 1167 passed, 1 skipped, the same count as main at fc38496.

[lywinged]

8a23a1b carries the "\n", is one signed commit on 5c69dc1, and the body now ticks Editorial alone. Same two-file diff, merges clean against fc38496, and the four ci.yml steps pass for me locally at 1167 passed, 1 skipped. Approving.

[imran-siddique]

Reviewed the documentation against the prior maintainer ruling and both released adapter implementations. The stated sandbox preimage includes the newline separator used by software_measurement, and the AGT example matches the SHA-256 chain-tip commitment. The change preserves the distinction between software commitments and hardware measurements.