The references rel registry: four governance requests are one question

[imran-siddique]

Why this exists

Four governance-shaped requests have arrived against this repository in about a week, from four unconnected contributors:

issue	ask
#191	binding attributable human-approval outcomes to step_up and defer execution evidence
#209	a public-sector auditability profile: policy exceptions, incident and escalation triggers
#220	per-action governance-decision evidence, independently verifiable with keys the operator does not control
external	a transition-closure layer, raised on #191

@lywinged identified the pattern on #209 before the fourth arrived:

All three need the same thing, which is a way to bind a governance fact that lives outside the record to the record itself. The demand is real and it is arriving faster than the profiles for it.

That reading is correct, and the consequence is that these should not be answered as four schema proposals.

The mechanism already exists

§3.1.2's references block, merged in #197, binds an external fact by rel, id, resolver, optional digest and optional retention, with the limit stated normatively: a verifier MUST NOT reject a record because a reference cannot be resolved, and MUST NOT treat a resolved reference as attested evidence.

Two registered values already cover part of the ground:

• authorized-intent, an authorization decided before execution, held in another system
• approval-outcome, an attributable human approval attached to a step-up or defer decision

So the composability question is settled. What is not settled is which further relationships get registered values, and what a verifier may conclude from each.

What this issue tracks

The rel registry as one question:

1. Which relationships need a registered value. Candidates from the four threads: a per-action policy evaluation (Governance-decision evidence as a composable layer in the Trust Record schema #220), a policy exception or rule violation (Public-sector auditability profile for verifiable AI agents #209), an incident or escalation trigger (Public-sector auditability profile for verifiable AI agents #209), and whatever spec: binding attributable human-approval outcomes to step_up and defer execution evidence #191 settles on beyond approval-outcome.
2. What each one's referenced object is, precisely enough that two implementations resolve the same thing.
3. What a verifier may and may not conclude from a resolved reference of each kind. §3.1.2 rule 3 sets the floor; each rel may need to say more.
4. Whether the registry is normative or informative, and therefore whether it needs an organisational sponsor under GOVERNANCE.md#who-may-author-normative-text.

Point 4 should be answered first, because it determines who can write the rest.

What this is not

Not a new schema layer, and not a new artifact. Each of the four proposals is smaller when expressed as a rel than as its own structure, and answering them separately would produce four overlapping mechanisms for one relationship type.

Related

#191, #209, #220, and #197 which merged the references block.

[nutstrut]

On point 4 — I think PR #199 gives a strong precedent for treating the rel registry as informative, while keeping the verifier behavior around references normative.

In #199, rel was deliberately opened from an enum to a plain string. The review rationale was that closing it “would make every new relation a schema change and a spec change at once,” with the registered values instead kept in the schema description and docs/schema.md. That seems like an intentional separation between an extensible vocabulary and the normative mechanics that interpret it.

What is already normative in §3.1.2 is the safety boundary: a verifier MUST NOT reject a record because a reference cannot be resolved, and MUST NOT treat a resolved reference as attested evidence. Those rules bind implementations. The registered rel values describe interoperable meanings on top of that mechanism.

That also seems consistent with CONTRIBUTING.md’s distinction between normative spec changes and informative additions. So my reading would be: keep the registry informative/extensible, and put any behavior that a verifier MUST or MUST NOT implement in §3.1.2 or the conformance rules rather than making each registered relationship itself a normative schema change.

One small documentation issue: the GOVERNANCE.md#who-may-author-normative-text anchor referenced in point 4 appears stale. The current sponsor rule I found is in CONTRIBUTING.md under “Spec changes (normative text).”

On point 1, one generic relationship worth considering is condition-appraisal: an independently produced appraisal of whether a specified condition is established by some evidence, where the referenced artifact carries its own verifier, provenance, and verification semantics.

I tested that shape using the current main-branch references model with an independently signed external appraisal receipt referenced by identifier and digest. The useful boundaries held: the receipt could be independently verified; an unresolvable reference did not invalidate the TRACE record; substituting an artifact with the wrong digest was detectable during resolution; and a referenced PASS or FAIL conclusion had no effect on TRACE record validity.

That suggests condition-appraisal could potentially cover the per-action policy-evaluation case without making TRACE responsible for the referenced appraisal’s semantics. Most importantly, resolving or successfully verifying such a reference would still not promote its conclusion into TRACE-attested evidence.

If that abstraction is too broad, the same experiment at least suggests a useful test for whatever rel is chosen: the relationship should describe what the external object means without changing §3.1.2’s existing non-upgrade boundary.

[lywinged]

On the #199 reading: it is right, and the merge commit hides the evidence for it, so here is the commit that carries it.

rel was closed when the block was first written: enum in the schema, Literal["authorized-intent", "approval-outcome", "behavior-trace"] in the model, matching origin.kind. It was opened in 3f4f05e, "schema: open rel and drop minItems, per review", for the reason quoted above. Diffing the squashed merge against its parent shows a plain string with no history, so the decision is not visible there.

Two things that commit records are worth having in this thread.

Opening it cost a guard, and the guard was replaced rather than dropped. The enum was doing real work: it made the registry mechanically checkable. What stands in for it is tests/test_references_block.py::test_the_registered_rel_values_stay_documented_in_all_three_places, which asserts that enum is absent from rel, that minLength stays 1, and that each registered value is named both in the schema description and in the references section of docs/schema.md. It fails if someone re-closes the set, and it fails if a registered value quietly stops being written down.

So informative here means an unregistered rel is legal. It does not mean unenforced, and that distinction seems worth carrying into whatever point 4 settles on.

The same commit dropped minItems: 1 on the same principle, and that principle bears on where the answer has to live. Nothing in §3.1.2 says the array must be non-empty, and a schema asserting what the normative text does not is the drift being avoided. The same holds for the registry: the schema is not the place the status gets decided, in either direction. §3.1.1 states closure for kind explicitly, "because the value of the field is that a verifier can key on it". §3.1.2 does not say that of rel. The implementation is reading that omission, and reading it as informative. If that is the intended answer, §3.1.2 saying so in a sentence would mean it no longer rests on a silence.

Checked on main rather than from the diff, since the point is what the code does:

registered rel (control)         schema accepted    signs and verifies
unregistered rel                 schema accepted    signs and verifies

An unregistered rel is not merely undocumented. It validates, and the record signs and verifies.