{
  "openapi": "3.1.0",
  "info": {
    "title": "Agentic Wine Constructor API",
    "version": "1.2.0",
    "description": "Creates a decision-ready custom and private-label wine commission dossier using human-authored compatibility rules and weighted criteria. A field-state constructor evaluates five vineyard controls before reception; the complete route follows nine method gates. Vineyard and cellar evidence remain subject to producer review."
  },
  "servers": [
    {
      "url": "https://vin-q.com"
    }
  ],
  "externalDocs": {
    "description": "Agentic Wine machine instructions",
    "url": "https://vin-q.com/agentic-wine.md"
  },
  "tags": [
    {
      "name": "Agentic Wine",
      "description": "Custom regenerative wine concepts, construction routes and producer-ready commission dossiers."
    }
  ],
  "paths": {
    "/api/constructor/dossier": {
      "get": {
        "operationId": "getConstructorOptions",
        "summary": "List custom-wine constructor options and workflow",
        "description": "Returns wine formats, sensory targets, geographic constraints, the field-state constructor, five vineyard controls and the nine method gates used to prepare a commission.",
        "tags": [
          "Agentic Wine"
        ],
        "responses": {
          "200": {
            "description": "Constructor options"
          }
        }
      },
      "post": {
        "operationId": "createWineCommissionDossier",
        "summary": "Create a producer-ready custom wine commission dossier",
        "description": "Turns a brand or event brief and wine target into a structured feasibility draft. The endpoint applies human-authored rules and weighted criteria, including a field-state constructor before reception. The response does not reserve grapes, certify availability or create a purchase.",
        "tags": [
          "Agentic Wine"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommissionBrief"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Decision-ready draft created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommissionDossier"
                }
              }
            }
          },
          "422": {
            "description": "Brief failed validation"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DecisionSystem": {
        "type": "object",
        "required": [
          "name",
          "version",
          "method",
          "adaptiveModelUsed",
          "humanReviewRequired"
        ],
        "properties": {
          "name": {
            "const": "Vin-Q Wine Constructor"
          },
          "version": {
            "const": "1.2.0"
          },
          "method": {
            "const": "human-authored-rules-and-weighted-criteria"
          },
          "adaptiveModelUsed": {
            "const": false
          },
          "humanReviewRequired": {
            "const": true
          }
        }
      },
      "CommissionDossier": {
        "type": "object",
        "required": [
          "schemaVersion",
          "decisionSystem",
          "dossierId",
          "createdAt",
          "status",
          "intent",
          "target",
          "candidateLots",
          "decisionGates",
          "fieldState",
          "vineyardModule",
          "vineyardIdentityOption",
          "productionRoute",
          "feasibility",
          "nextAction"
        ],
        "properties": {
          "schemaVersion": {
            "const": "1.2"
          },
          "decisionSystem": {
            "$ref": "#/components/schemas/DecisionSystem"
          },
          "dossierId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "const": "decision-ready-draft"
          },
          "intent": {
            "type": "object"
          },
          "target": {
            "type": "object"
          },
          "candidateLots": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "decisionGates": {
            "type": "array",
            "minItems": 9,
            "maxItems": 9,
            "items": {
              "$ref": "#/components/schemas/DecisionGate"
            }
          },
          "vineyardModule": {
            "type": "array",
            "minItems": 5,
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/VineyardControlGate"
            }
          },
          "vineyardIdentityOption": {
            "type": "object"
          },
          "productionRoute": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "feasibility": {
            "type": "object"
          },
          "nextAction": {
            "type": "object"
          },
          "fieldState": {
            "$ref": "#/components/schemas/FieldState"
          }
        }
      },
      "DecisionGate": {
        "type": "object",
        "required": [
          "code",
          "id",
          "name",
          "decision",
          "measurements"
        ],
        "properties": {
          "code": {
            "enum": [
              "G0",
              "G1",
              "G2",
              "G3",
              "G4",
              "G5",
              "G6",
              "G7",
              "G8"
            ]
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "decision": {
            "type": "string"
          },
          "measurements": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "VineyardControlGate": {
        "type": "object",
        "required": [
          "code",
          "parentGate",
          "name",
          "decision",
          "measurements",
          "output"
        ],
        "properties": {
          "code": {
            "enum": [
              "G2.1",
              "G2.2",
              "G2.3",
              "G3.1",
              "G3.2"
            ]
          },
          "parentGate": {
            "enum": [
              "G2",
              "G3"
            ]
          },
          "name": {
            "type": "string"
          },
          "decision": {
            "type": "string"
          },
          "measurements": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "output": {
            "type": "string"
          }
        }
      },
      "CommissionBrief": {
        "type": "object",
        "required": [
          "intent",
          "target"
        ],
        "properties": {
          "intent": {
            "type": "object",
            "required": [
              "projectName",
              "organization",
              "occasion",
              "bottleCount",
              "targetRelease",
              "producerSharingConsent"
            ],
            "properties": {
              "projectName": {
                "type": "string"
              },
              "organization": {
                "type": "string"
              },
              "occasion": {
                "type": "string"
              },
              "audience": {
                "type": "string"
              },
              "bottleCount": {
                "type": "string"
              },
              "targetRelease": {
                "type": "string"
              },
              "labelDirection": {
                "type": "string"
              },
              "producerSharingConsent": {
                "type": "boolean",
                "description": "Explicit authorization to share the dossier and contact identity with registered producers."
              }
            }
          },
          "target": {
            "type": "object",
            "required": [
              "format",
              "color",
              "aroma",
              "structure",
              "geographicDesignation"
            ],
            "properties": {
              "format": {
                "enum": [
                  "still",
                  "sparkling"
                ]
              },
              "color": {
                "enum": [
                  "red",
                  "white",
                  "rose"
                ]
              },
              "aroma": {
                "type": "string"
              },
              "structure": {
                "type": "string"
              },
              "geographicDesignation": {
                "enum": [
                  "none",
                  "dop-cava",
                  "do-penedes",
                  "doq-priorat"
                ]
              },
              "organicRequired": {
                "type": "boolean"
              }
            }
          },
          "candidateLots": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "variety": {
                  "type": "string"
                },
                "origin": {
                  "type": "string"
                },
                "role": {
                  "type": "string"
                },
                "compatibilityState": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "FieldState": {
        "type": "object",
        "required": [
          "id",
          "title",
          "definition",
          "decisionRule",
          "controls"
        ],
        "properties": {
          "id": {
            "const": "field-state"
          },
          "title": {
            "type": "string"
          },
          "definition": {
            "type": "string"
          },
          "decisionRule": {
            "type": "string"
          },
          "controls": {
            "type": "array",
            "minItems": 5,
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/FieldStateControl"
            }
          }
        }
      },
      "FieldStateControl": {
        "type": "object",
        "required": [
          "code",
          "name",
          "decision",
          "measurements",
          "output"
        ],
        "properties": {
          "code": {
            "enum": [
              "F0.1",
              "F0.2",
              "F0.3",
              "F0.4",
              "F0.5"
            ]
          },
          "name": {
            "type": "string"
          },
          "decision": {
            "type": "string"
          },
          "measurements": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "output": {
            "type": "string"
          }
        }
      }
    }
  }
}