Record why model_ref narrowing shipped without an API version

[xmap]

Item 4 of the brain-arc follow-ups. Docs only, no code.

What the decision is

The Brain change made model_ref nullable on AgentResponse. It had been required and non-null:

before   required: [id, kind, name, version, model_ref, status, capabilities]
after    required: [id, kind, name, version,            status, capabilities]

A field that was always present becoming sometimes absent breaks a caller that dereferenced it without checking, which the type said it never had to do. Under the additive-default stance that is breaking, and it shipped with no X-Cora-Api-Version header. That was the right call, for reasons not visible in the diff.

Two are durable. The withdrawn guarantee was a guarantee to return a sentinel: a rule-brained agent had no model to name, so the field carried provider deterministic, model agent:<Name>:v1. A caller reading model_ref.provider got a provider naming no vendor and a model never called or approved. And brain was added alongside as a strictly better replacement.

The third is that there are no consumers, and it does most of the work while being the one that expires. It is written with the expiry attached: once the REST surface has any consumer outside this repository, this precedent stops applying. Without that sentence the next narrowing change cites this section for "CORA does not version," and a narrow sentinel argument quietly becomes a general licence.

Also recorded

What the openapi.json snapshot buys. test_openapi_drift catches drift, so every contract change is visible in a diff; whether a given diff is additive or breaking is still a judgement. That is why the reasoning belongs in prose next to the snapshot rather than in the diff alone.

A count corrected while writing it

I counted rather than quoting the design memo, and the memo was wrong. AgentSeedIdentity(...) constructions in src/cora: 24, of which 18 are rule-brained and 6 name a model. The memo said "twenty seeded agents, eighteen Rule, two LanguageModel", which does not add up. The six are two agent roles (RunDebriefer, CautionDrafter) across three deployment profiles each. The doc states it as seed definitions and says so explicitly, since roles and definitions differ by a factor of three on that side.

Docs build clean under --strict; 37,425 architecture tests passing.

🤖 Generated with Claude Code

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.