spec: name the two attestation classes in §5.2, with a worked example

[eeee2345]

Closes #65.

@mindpower — you asked for this on the issue ("Please go ahead and open a PR with the updated wording. Adding a worked example to the conformance/ directory would also be incredibly helpful"). Noting the README's normal route for normative changes is that a maintainer lands them, so this is opened on that invitation rather than around the policy — happy for it to be taken over as a maintainer commit instead.

It also sat for 34 days, during which #70 landed and moved the ground. Rebased on current main; what that changed is in the last section.

The problem

§5.2's type examples are all organizational-compliance attestations, so a filter match on trustManifest.attestations.type reads as a safety verdict on the artifact when it is a statement about the publisher. #52 raised this from the caution side. This resolves it from the vocabulary side: name the two classes, so the filter semantics become meaningful rather than only warned against.

What is here

• spec/ard.md §5.2 — names compliance attestations and scan attestations, states which one is an artifact-scoped claim, and adds one normative sentence for registries and orchestrators.
• conformance/examples/scan-attestation/ — one entry carrying one attestation of each class, plus the SARIF document the scan attestation references.
• spec/ard.md §5.2 table — adds the missing mediaType row (see below).

Three things from the draft in #65 are deliberately not here

No type token. The draft added agent-threat-scan to the type examples. It has no normative definition source in this repo and there is no attestation type registry — #48 proposed one and was closed pending an external spec being accepted, which is the same shape. So the class is named and the token is not. The example uses a value because a publisher must, and its README says that value is a publisher's choice rather than spec vocabulary.

No claim on digest. The draft said a scan attestation SHOULD carry a digest bound to the scanned artifact. ai-catalog.schema.json defines that member as the digest of the attestation document, and the item is additionalProperties: false, so the binding cannot live there without a new member. The requirement now falls on the referenced document, which is where in-toto and SARIF already put it, and the text says explicitly which of the two the member covers. If a field-level subject binding is wanted, that is a separate proposal.

Nothing in the v0.91 draft or the schemas. The go-ahead on #65 predates #70, so those were never discussed. Flagging two things for whoever picks that up: §4.5 now requires registries to use attestations in filtering and ranking while the §5.1–5.3 tables were removed, so the semantics need a home there too; and both schemas still describe attestations as compliance-only, which is the same over-reading in machine-readable form.

The mediaType row

ai-catalog.schema.json has required: ["type", "uri", "mediaType"] but the §5.2 table lists only type, uri and digest. Pre-existing, but the example surfaced it — it cannot validate without a mediaType — and the PR is already editing those rows.

The example

One attestation of each class, because the difference is only visible side by side. The SARIF document is included so the chain is followable rather than described: the entry's digest covers that document and is recomputable from the file, and the document names the tool, version and ruleset it ran under, and identifies the scanned subject by hash in runs[].artifacts[].hashes.

The scanned artifact is not vendored — in a deployment the publisher serves it at the entry's url — so its hash inside the SARIF is illustrative, and the README says so rather than implying otherwise.

Verification

./bin/conformance-test manifest examples/scan-attestation/ai-catalog.json
  CONFORMANCE STATUS: PASS — 0 critical errors, 0 warnings

./bin/run-conformance-demo
  ALL CONFORMANCE CHECKS PASSED

One thing worth knowing: run-conformance-demo validates every *.json under conformance/examples as a catalog, so an example directory that needs a non-catalog JSON fixture fails the demo. The scan document here is .sarif, which sidesteps it, but the glob is probably worth tightening before someone hits it with a file that has to be .json.

[mindpower]

Thanks for putting up this PR.

Drawing a clear line between organizational compliance (like SOC 2) and actual artifact scan results (SARIF) makes a lot of sense. It stops folks from waving a SOC 2 cert around as proof that the code itself is secure. Good catch on adding mediaType back into the §5.2 table to sync with the schema as well (Please also check and make sure sync with latest repo as we have recently updated the spec to 0.91).

I also liked the callout in the doc about digests binding content, not honesty. If enterprises want cryptographic proof that a third-party scanner (e.g., Palo Alto, Snyk) actually ran the check rather than trusting a self-reported SARIF file, wrapping it in an in-toto DSSE envelope fits naturally here since mediaType is kept open.