From b8804d6823374c6efcb576d3d2a6924f9d5f48bf Mon Sep 17 00:00:00 2001 From: Imran Siddique Date: Wed, 2 Sep 2026 12:25:37 -0700 Subject: [PATCH] docs(schema): read runtime.platform's two situations as examples #234 aligned the schema description with spec 3.1.1, but its enumeration reads as exhaustive. The lead clause is "no hardware root of trust"; the two named situations are a development-mode execution and a record assembled from evidence produced outside the runtime. A production runtime emitting for its own executions, origin.kind self, with no TEE anywhere in its stack, is covered by the lead clause and named by neither, so the description narrowed the rule again in a smaller way. "For example" restores the reading without adding a case or diverging from docs/schema.md. Both schema copies carry it. Raised by @chernistry on #232 and again on #234. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_012yyHFd4YA35oNUjhrztJSb --- CHANGELOG.md | 2 ++ schema/trace-claim.json | 2 +- src/agentrust_trace/schema/trace-v0.2.json | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f57636..d4d1d8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ Format: [Semantic Versioning](https://semver.org/). Spec versions follow `MAJOR. ### Fixed +- **`runtime.platform`'s description now reads its two situations as examples rather than as the whole set.** #234 aligned the schema description with spec 3.1.1, whose lead clause is "no hardware root of trust" and whose enumeration names a development-mode execution and a record assembled from evidence produced outside the runtime. A production runtime emitting for its own executions, `origin.kind: self`, with no TEE anywhere in its stack, is covered by the lead clause and named by neither example, so the enumeration read as exhaustive and narrowed the rule again in a smaller way. "For example" restores the reading without adding a case or diverging from `docs/schema.md`. Both schema copies carry it. Raised by @chernistry on [#232](https://github.com/agentrust-io/trace-spec/issues/232) and on [#234](https://github.com/agentrust-io/trace-spec/pull/234). + - **`schema/trace-claim.json`'s `runtime.platform` description now states the same rule as spec 3.1.1.** The schema description said `software-only` marks "development-mode records with no hardware backing", which is narrower than what 3.1.1 requires: a record whose `origin.kind` is not `self` MUST also carry `runtime.platform: "software-only"`, a class that is not development-mode records. `docs/schema.md` already stated the two-situation rule (dev-mode execution, or evidence assembled from outside the runtime); only the schema description, the text closest to a validator and most integrators, was out of step. Same shape as [#172](https://github.com/agentrust-io/trace-spec/issues/172), resolved the same way: aligning the texts rather than picking one as authoritative. [#232](https://github.com/agentrust-io/trace-spec/issues/232) - **The schema's `subject` pattern was a prefix test where the model requires a full identity, so a record could be schema-conformant and refused by `model_validate`.** `^(spiffe://|did:)` constrains only a leading `spiffe://` or `did:`; `models.py` requires `^(spiffe://[^/]+/.+|did:[a-z0-9]+:.+)$`. `spiffe://bernstein.run` names a trust domain and no workload, and passed the published artifact a producer in any language validates against. The schema is tightened to the model rather than the model loosened: a bare prefix is not a constraint on an identity, and the model's rule matches DID Core section 3.1, whose ABNF fixes `method-char` to `%x61-7A / DIGIT`, so `did:X:abc` is not a conformant DID rather than a DID this package happens to refuse. Both schema copies carry the change and both now state the rule in prose instead of leaving it to be read off a regex. The differential in `tests/test_the_schema_and_the_models_agree.py` could not see this: `subject`'s pattern was a prefix test, so every value in its matrix failed it too and the two validators agreed by both rejecting. Four values that pass the prefix and fail the shape are added, and they are the only pair of patterns among the schema's ten that differed. The two surfaces parted at `84df8ef` ("security: pre-launch hardening", #49, 2026-06-18), which tightened the model's pattern from `^(spiffe://|did:)` to the current one and left the schema on the old string; `docs/schema.md` still described the prefix reading and is corrected here too. diff --git a/schema/trace-claim.json b/schema/trace-claim.json index d547fe0..985ef6e 100644 --- a/schema/trace-claim.json +++ b/schema/trace-claim.json @@ -119,7 +119,7 @@ "tpm2", "software-only" ], - "description": "Hardware platform providing the root of trust. software-only marks records with no hardware root of trust: a development-mode execution, or a record assembled from evidence produced outside the runtime (origin.kind other than self requires this value; see spec 3.1.1). Such records must never be treated as attested evidence." + "description": "Hardware platform providing the root of trust. software-only marks records with no hardware root of trust, for example a development-mode execution, or a record assembled from evidence produced outside the runtime (origin.kind other than self requires this value; see spec 3.1.1). Such records must never be treated as attested evidence." }, "measurement": { "type": "string", diff --git a/src/agentrust_trace/schema/trace-v0.2.json b/src/agentrust_trace/schema/trace-v0.2.json index d547fe0..985ef6e 100644 --- a/src/agentrust_trace/schema/trace-v0.2.json +++ b/src/agentrust_trace/schema/trace-v0.2.json @@ -119,7 +119,7 @@ "tpm2", "software-only" ], - "description": "Hardware platform providing the root of trust. software-only marks records with no hardware root of trust: a development-mode execution, or a record assembled from evidence produced outside the runtime (origin.kind other than self requires this value; see spec 3.1.1). Such records must never be treated as attested evidence." + "description": "Hardware platform providing the root of trust. software-only marks records with no hardware root of trust, for example a development-mode execution, or a record assembled from evidence produced outside the runtime (origin.kind other than self requires this value; see spec 3.1.1). Such records must never be treated as attested evidence." }, "measurement": { "type": "string",