Add first-consumer model request and result contract

[mark-e-deyoung]

Purpose

Implements #35 as the missing versioned request/result boundary between exact native materialization and qualification receipt binding.

The first-consumer receipt binds request.digest, and the changed-envelope gate compares request digests. This PR makes that identity concrete without implementing a general planner.

Request v1

The request contains only project requirement facts:

• capability + versioned interface;
• opaque target profile ID;
• offline requirement + allowed runtime IDs;
• allowed representation IDs + quantizations;
• only resource/performance limits actually declared by the experiment;
• frozen project quality-policy ID + digest.

Provider/model/acquisition/token/local-handle fields are rejected as invalid request fields. Allowed runtime/representation/quantization arrays are canonicalized so input ordering does not change request identity.

Result v1

Exactly one status:

• qualified — stable exact selection + retained qualification subject/record;
• candidate — stable exact proposed selection, explicitly not qualified;
• unknown — unresolved deterministic knowledge with reason(s), no fake selection;
• rejected — deterministic rejection with reason(s), no fake selection.

A selection now binds only stable chosen-artifact facts: provider, repository, immutable source revision, representation/quantization, runtime ID, and target profile. Provider-observation digests/refs belong in the existing result evidence array rather than selection identity.

2026-09-04 provider-identity correction

Cross-contract red-team found that selection.artifact.observation_digest imported observation-event identity into the stable selection. Because a normalized observation may change on metadata recapture while the exact immutable provider revision does not, this could perturb retained binding content without any actual model selection change.

The correction removes that redundant field rather than adding a new artifact-identity framework. V1 remains conservative across different immutable provider revisions.

Identity

request_digest = sha256(canonical normalized request JSON).

Changing target, offline policy, runtime, representation, quantization, quality policy, or any declared envelope limit changes the digest. Wall clock/storage location is absent from the request identity.

Fixture warning

The numeric envelope values in the committed KV-Ground-shaped request fixture are contract-test values only, not approved first-consumer resource/performance thresholds. The real envelope and measurement procedure must be frozen separately before observing candidate performance.

Included

• schemas/model-request-v1.schema.json
• schemas/model-plan-result-v1.schema.json
• tools/model_request_contract.py
• deterministic first-consumer-shaped request fixture
• contract tests, including observation-as-evidence rather than selection-identity behavior
• boundary documentation
• unprivileged public offline CI

Deliberate non-goals

No model ranking, catalog/database, provider discovery, target scanner, Generator–Validator implementation, model acquisition, consumer runtime mutation, or private target/workload data.

Stack

• base: Foundry PR Add exact-revision Hugging Face native materialization #30 / impl/issue-29-hf-native-materialization at 7380395be39934407565edb8717eb56afb77f728;
• current corrected request/result head: 0ac14c7e477f830cc23554a674517f0170020ecb;
• descendants PR Add deterministic qualification receipt binding #32/Add deterministic retained qualification resolution #38/Freeze first-consumer GO NARROW KILL gate #34 must carry this corrected stable-selection shape before the real deterministic-repeat proof.

R4

Canonical, offline, byte-repeatable, no runtime/provider side effects, independently reversible, and provider-observation recapture does not alter stable selection identity.

Related: #18, #19, #31, #33, #35, #37; draft PRs #30/#32/#38/#34; SemperSupra/desktop-ui-cv#35.