feat(10-02): relation field options and relation saves with labels

- FieldRelationContract/FieldRelationProvider bind every type: relation
  field to a belongsTo foreign key or a belongsToMany pivot; activation
  fails naming plugin, controller and field on a missing or broken contract
- GET /{vendor}/{plugin}/{controller}/fields/{field}/options serves
  {value, label} pages scoped by pact.RelationExtendOptionsQuery, behind
  the controller permission; read-only and non-relation fields are 404
- Saves apply present relation keys after the Before hook: ids are
  revalidated through the same scoped query (422 and full rollback
  otherwise), belongsTo sets the foreign key, belongsToMany replaces pivot
  rows in submitted order with the order column set to the index
- Show, create and update return relation values in data and meta.labels
- A belongsTo on a protected fill key is read-only (D-26)
- One six-segment GET pattern dispatches relation lists and field options,
  which ServeMux cannot register side by side
- Admin OpenAPI documents the options route and RecordEnvelope

cabana/admin_openapi.go

@@ -257,6 +257,28 @@ func AdminFormSchema() {}
 // @Router /{vendor}/{plugin}/{controller}/schema/relation/{name} [get]
 func AdminRelationSchema() {}
 
+// AdminFieldOptions documents the relation field options route (D-17).
+//
+// @Summary Relation field options
+// @Description Choices for a writable `type: relation` field: value is the related id, label its nameFrom column. Read-only and non-relation fields answer 404.
+// @Tags admin
+// @Produce json
+// @Security BackendBearer
+// @Param vendor path string true "Vendor"
+// @Param plugin path string true "Plugin"
+// @Param controller path string true "Controller"
+// @Param field path string true "Relation field name"
+// @Param search query string false "Case-insensitive label search"
+// @Param page query integer false "Page"
+// @Param per_page query integer false "Options per page (1-100, default 20)"
+// @Success 200 {object} ListEnvelope[[]RelationOption]
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 422 {object} ErrorEnvelope
+// @Router /{vendor}/{plugin}/{controller}/fields/{field}/options [get]
+func AdminFieldOptions() {}
+
 // AdminList documents the record list route.
 //
 // @Summary List admin records
@@ -281,6 +303,7 @@ func AdminList() {}
 // AdminCreate documents the record create route.
 //
 // @Summary Create an admin record
+// @Description Relation fields are sent by field name with ids ({"genre": 3, "artists": [4, 9]}); the response carries the same shape plus meta.labels.
 // @Tags admin
 // @Accept json
 // @Produce json
@@ -288,7 +311,7 @@ func AdminList() {}
 // @Param vendor path string true "Vendor"
 // @Param plugin path string true "Plugin"
 // @Param controller path string true "Controller"
-// @Success 200 {object} SuccessEnvelope
+// @Success 201 {object} RecordEnvelope
 // @Failure 401 {object} ErrorEnvelope
 // @Failure 403 {object} ErrorEnvelope
 // @Failure 422 {object} ErrorEnvelope
@@ -322,7 +345,7 @@ func AdminBulkDelete() {}
 // @Param plugin path string true "Plugin"
 // @Param controller path string true "Controller"
 // @Param id path integer true "Record id"
-// @Success 200 {object} SuccessEnvelope
+// @Success 200 {object} RecordEnvelope
 // @Failure 401 {object} ErrorEnvelope
 // @Failure 403 {object} ErrorEnvelope
 // @Failure 404 {object} ErrorEnvelope
@@ -340,9 +363,10 @@ func AdminShow() {}
 // @Param plugin path string true "Plugin"
 // @Param controller path string true "Controller"
 // @Param id path integer true "Record id"
-// @Success 200 {object} SuccessEnvelope
+// @Success 200 {object} RecordEnvelope
 // @Failure 401 {object} ErrorEnvelope
 // @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
 // @Failure 422 {object} ErrorEnvelope
 // @Router /{vendor}/{plugin}/{controller}/{id} [put]
 func AdminUpdate() {}