spec: where a verifier records an unresolvable citation: the cross-surface question from #187's review

[opento-suggestions]

#187 has merged. Its review asked for a tracking marker on one cross-cutting item — "an explicit line in §3.2.3 — that the field for this is deferred, with an issue number" — and that issue does not yet exist. This is that issue. It records the question as deferred; it does not propose the answer.

The question, as the review put it: when a record cites something a verifier cannot resolve, what does the verifier record, and where.

Four surfaces currently answer it three different ways, or not at all:

• build_provenance — answered and merged (feat(schema): declare build_provenance verification depth (#50) #173): the depth actually achieved is recorded in a dedicated field, appraisal.provenance_depth_verified, and appraisal.status moves to contraindicated only when a configured floor is not met.
• Revocation — merged (spec: anchor key revocation to log entry ordering, not iat (#67) #187): the spec text states "Neither may be reported as an affirming appraisal" with no field or value naming what is reported instead. The review walks the enum: contraindicated reports evidence failing, none reports no appraisal performed, warning reports evidence passing — each misreports a check that was merely unresolvable.
• Delegation links — open (rfc(draft, non-normative): A2A delegation-link verification profile, with 23 conformance vectors #184): the same boundary is classed unverifiable, deliberately distinct from both invalid kinds, on its own axis.
• appraisal.policy_ref — raised on [pre-v1.0] Verification depth + action_receipts: two-axis verification model #66: whether resolution of the appraisal policy citation falls under the same discipline.

Two conformant verifiers implementing today's merged text can record different things for the same unresolvable check on the same record. That is the divergence the depth work closed for build_provenance, reappearing on every other surface that cites by reference.

Scope of this issue: a home for the decision, not the decision. The review already names the merged shape that fits — a recorded field plus a policy floor, per #173 — and whether a field lands, and where, is a schema question for the editorial process. What this number enables immediately:

• normative text can cite it where the merged prose currently says only what may not be reported;
• conformance vectors on both active sides — the revocation vectors claimed in spec: anchor key revocation to log entry ordering, not iat (#67) #187's triage, and the appraisal-resolution vectors accepted on [pre-v1.0] Verification depth + action_receipts: two-axis verification model #66 — can mark their unresolvable-case vectors as deferred pending this issue, rather than each coining an outcome value and making the count of conventions five and six.

If the editorial preference is to fold this into an existing tracker instead, closing this as a duplicate with a pointer serves the same purpose.

[lywinged]

#184 is mine and the enum walk on revocation is from my review, so I can confirm both of those readings. #184 does class this unverifiable, on an axis separate from both invalid kinds, and the walk is what I meant by it: contraindicated reports evidence that failed, none reports a check nobody ran, warning reports evidence that passed, and an unresolvable citation is none of those.

One correction to the framing though, and it is against my own entry. #184 is a draft and explicitly non-normative, so unverifiable there is a proposal rather than a fourth established answer. If the spec settles this differently, #184 changes. It belongs in the list as a surface facing the question, not as one of the ways it has already been answered.

Worth adding why all four diverged, because it is one schema read rather than an opinion. In schema/trace-claim.json, appraisal is additionalProperties: false, with policy_ref, provenance_depth_verified, status, timestamp, verifier, and status is affirming | warning | contraindicated | none. Across the whole schema the only other depth field is build_provenance.provenance_depth, which is what a producer declares rather than what a verifier reached. So #173 landed a pair, a claimed depth and a verified one, and that pair exists for a single surface. The other three have neither half, and appraisal is closed, so they did not choose prose over a field. There was no field for them to use.

On what is doable now. A new field or a fifth status value is normative under CONTRIBUTING, which routes it through a Spec change proposal, five business days and a sponsoring organization, so it is not solo work.

Vectors on their own would have nothing to run against, which is the more useful thing to say, and it points at where the work actually is.

The input format is already merged. schema/trace-revocation-bundle.json landed with #187 and requires type, log_id, issued_at, valid_until, statements, bundle_key_id and sig. Nothing consumes it. valid_until appears zero times under src/; RevocationStore in sign.py is Container[str] | Callable[[str], bool], a bool with no bundle and no age in it; and _check_not_revoked raises both for a revoked key and for a status it cannot determine, which are two of the outcomes §3.2.3 now separates. verify_record returns None or raises, so there is no channel for a third.

So the piece is a consumer for a schema that already exists: take a bundle, and distinguish verified against it, unverified for revocation because the newest one is past the profile's maximum age, and no check performed because there is none. Nothing needs designing. The schema fixes the input and §3.2.3 fixes the three outcomes and the prohibition on reporting any of them as affirming. The vectors then have something to run, in examples/, and the sets already there show the shape: a record, the key it declares, and an expected block.

It implements merged text rather than proposing any, so no sponsor, and it stops one step short of this issue. A function can return three states without anyone deciding which appraisal.status value two of them carry.

[imran-siddique]

Keeping this issue as the home for the normative question, and greenlighting the consumer work, which is separable from it.

@lywinged's schema read is right and I checked all of it at main dba52b3 rather than taking it:

• valid_until appears in spec/trace-v0.2.md, docs/verification.md, schema/trace-revocation-bundle.json and tests/test_revocation_schema.py, and zero times under src/. The bundle format merged with spec: anchor key revocation to log entry ordering, not iat (#67) #187 and nothing consumes it.
• RevocationStore is Container[str] | Callable[[str], bool]. A bare boolean with no bundle and no age in it.
• _check_not_revoked raises both for a revoked key and for a status it cannot determine, and its own docstring says both fail closed. §3.2.3 now separates exactly those two.
• verify_record returns None or raises, so there is no channel for a third outcome even if the code distinguished one.

And the correction against your own entry is the right one: #184 is a draft and explicitly non-normative, so its unverifiable is a proposal, not a fourth answer. Listing it as a surface facing the question rather than one of the ways it has been answered is more accurate, and I would rather have that correction than the tidier framing.

The explanation for why the four diverged is the part that changes what I do here. It is not that three surfaces chose prose over a field. appraisal is additionalProperties: false and status is closed at four values, so #173 landing a claimed-depth and verified-depth pair for build_provenance gave that one surface somewhere to put the answer, and the other three have nowhere. That makes this a schema gap rather than a drafting inconsistency, and it is why prose alone could not have closed it.

Parked here, deliberately

The field, or a fifth status value, is normative. Under CONTRIBUTING that is a Spec change proposal with a sponsoring organization and five business days, so it is not something either of you can carry and not something I am going to settle in a comment. This issue stays open as the marker, and merged prose can cite this number where it currently states only what may not be reported.

Greenlit now, no sponsor needed

Build the revocation-bundle consumer. Take a bundle validated against the merged trace-revocation-bundle.json, and distinguish three states:

1. verified against the bundle;
2. unverified for revocation, because the newest bundle is past the profile's maximum age;
3. no check performed, because no bundle was supplied.

That implements merged text rather than proposing any, so the sponsor rule does not reach it, and it stops exactly one step short of this issue: a function may return three states without anyone deciding which appraisal.status value two of them carry. Keep it there. If the implementation ends up naming an outcome, it has gone too far and has pre-empted the decision this issue exists to hold.

Two things to settle inside that scope, and they are yours rather than mine:

verify_record currently returns None or raises, so the third state needs a channel. Whether that is a new return type, an out-parameter, or a separate entry point is a design call worth proposing in the PR rather than picking silently, because it is the shape every future unresolvable-citation check will inherit.

The profile's maximum bundle age has to come from somewhere the caller controls. valid_until is in the bundle, but a bundle asserting its own acceptable staleness is the same shape of problem as a record asserting its own approval threshold.

Vectors then have something to run against, in examples/, following the shape already there.

@opento-suggestions: this also answers the deferral on your appraisal-resolution vectors. Outcomes there that wait on a value in the appraisal.status enum genuinely wait on this issue. Outcomes that are a finding status, one layer down, do not, which is the point I made on trace-tests#69.