MVP request/result contract for first ui-grounding consumer

[mark-e-deyoung]

Purpose

Implement the smallest versioned project-facing request/result contract required by Foundry #18/#19 and the first desktop-ui-cv KV-Ground proving slice.

This closes a concrete contract gap: qualification receipt v1 already binds a canonical request.digest, and the changed-envelope decision gate compares request digests, but no versioned request object yet defines what facts make the first consumer request materially different.

Boundary

This increment defines and canonicalizes the contract only. It does not implement candidate research, model ranking, a catalog/database, Generator–Validator exploration, hardware discovery, or real qualification.

Request v1 — minimum first-consumer envelope

The canonical request must bind only facts that can materially affect the first selection/qualification decision:

• schema version;
• capability:
  • id (first case: ui-grounding);
  • versioned consumer interface;
• target profile ID — opaque stable target/deployment profile reference;
• runtime requirement:
  • offline serving required;
  • allowed runtime IDs;
• representation requirement:
  • allowed representation IDs;
  • allowed quantization modes;
• bounded service/resource envelope:
  • maximum steady-state VRAM GiB when applicable;
  • maximum model-load/startup seconds;
  • maximum per-query grounding latency milliseconds;
• project quality policy digest/reference used for the qualification requirement.

Do not put provider URL/token, model repository, selected model, local filesystem path, or acquisition instructions in the request. Those are outputs/evidence, not project requirements.

Optional resource limits may be omitted only when they are genuinely unconstrained for the experiment; do not invent numeric limits merely to fill fields.

Canonical request identity

Provide a stdlib-only canonicalizer/validator that computes:

request_digest = sha256(canonical request JSON)

The digest must be independent of storage/reference location and wall clock.

Tests must prove:

• same semantic request -> same digest;
• key/input ordering does not affect canonical output;
• changing target profile, offline requirement, runtime, representation, quantization, quality policy, or any declared resource/performance limit changes the digest;
• adding provider/model/acquisition/local-handle fields is rejected rather than silently ignored.

Result v1

The planner/result contract may return only:

• qualified — a retained qualification subject is already known for this exact request/target envelope;
• candidate — a specific exact candidate/materialization is proposed but not yet qualified for this subject;
• unknown — deterministic retained knowledge is insufficient; bounded exploration may be justified;
• rejected — the request/candidate set is deterministically infeasible or disallowed for explicit reasons.

Every result must bind the canonical request digest and explicit reasons/evidence references.

Qualified result

Must reference:

• retained qualification subject_key;
• qualification record_digest;
• selected exact artifact observation digest;
• representation ID/variant/quantization;
• runtime ID;
• target profile ID.

Do not include a machine-local model path as durable result identity.

Candidate result

Must identify the exact proposed artifact observation plus representation/runtime/target and may reference a materialization receipt. It must not claim qualification.

Unknown result

Must provide one or more explicit unresolved reasons. It must not contain a fake selected/qualified candidate merely to fill the schema.

Rejected result

Must provide one or more explicit rejection reasons. A rejected result is deterministic evidence and does not automatically invoke Generator–Validator.

Deterministic known-path behavior

Add a small helper/fixture proving the contract can express:

1. exact request -> retained qualified result;
2. exact unsupported request -> unknown with reason;
3. deterministic hard rejection -> rejected with reason.

Do not implement a generalized planner or persistent catalog in this increment.

Privacy/security

• no credentials;
• no private raw hardware inventory required in the public request; target profile can remain opaque;
• no private screenshot/workload bytes;
• evidence references are references, not publication/ownership claims.

Stack placement

Place this contract after exact HF native materialization PR #30 and before qualification receipt PR #32.

After this PR is opened, retarget PR #32 to this contract branch so the public critical path becomes:

... -> PR #30 -> request/result contract -> PR #32 qualification receipt -> PR #34 decision gate

R4

• reproducible: canonical versioned schemas/fixtures;
• repeatable: same request produces same digest;
• reversible: contract-only increment, no consumer runtime changes;
• idempotent: repeat canonicalization/build is byte-identical.

Non-goals

• no model selection algorithm;
• no candidate ranking score;
• no target scanner;
• no provider discovery;
• no broad model ontology;
• no Generator–Validator implementation;
• no consumer runtime mutation;
• no merge/release/deploy.

Exit

Leave a verified public draft PR. The first real desktop-ui-cv request can then be frozen before KV-Ground qualification, and the changed-envelope experiment has a mechanically meaningful identity boundary.

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