{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentpay-so/json-schema/agentpay-so-commerce-compile-response-schema.json",
  "title": "CommerceCompileResponse",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentpay-so-openapi.yml#/components/schemas/CommerceCompileResponse",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "packet",
    "signature"
  ],
  "properties": {
    "packet": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "discovery",
        "compilation"
      ],
      "properties": {
        "schema": {
          "type": "string",
          "const": "agentpay.commerce-compilation-packet/1.1"
        },
        "discovery": {
          "$ref": "#/$defs/CommerceDiscoveryReport"
        },
        "compilation": {
          "$ref": "#/$defs/CommerceCompilation"
        }
      }
    },
    "signature": {
      "$ref": "#/$defs/SignedPacketSignature"
    }
  },
  "$defs": {
    "BuyerConstitution": {
      "type": "object",
      "additionalProperties": false,
      "description": "Human-owned hard limits enforced before any model ranking.",
      "required": [
        "currency",
        "maxTotalMinor",
        "allowedCategories"
      ],
      "properties": {
        "currency": {
          "type": "string",
          "pattern": "^[A-Za-z]{3}$"
        },
        "maxTotalMinor": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100000000000
        },
        "allowedCategories": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": {
            "type": "string",
            "maxLength": 120
          }
        },
        "allowedMerchants": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "type": "string",
            "maxLength": 120
          }
        },
        "blockedMerchants": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "type": "string",
            "maxLength": 120
          }
        },
        "requiresRefundable": {
          "type": "boolean",
          "default": false
        },
        "minimumReturnWindowDays": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3650
        },
        "maximumDeliveryDays": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3650
        },
        "maxEvidenceAgeMinutes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 525600,
          "default": 1440
        },
        "requireHumanApproval": {
          "type": "boolean",
          "default": true
        },
        "autoApproveBelowMinor": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100000000000
        },
        "weights": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "price": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "quality": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "delivery": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "sustainability": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            }
          }
        }
      }
    },
    "CommerceCompilation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "source",
        "model",
        "selectedProductId",
        "alternateProductId",
        "confidence",
        "ranking",
        "verification",
        "fallbackReason",
        "retention"
      ],
      "properties": {
        "schema": {
          "type": "string",
          "const": "agentpay.commerce-compilation/1.0"
        },
        "source": {
          "type": "string",
          "enum": [
            "gpt-5.6-verified",
            "deterministic"
          ]
        },
        "model": {
          "type": [
            "string",
            "null"
          ]
        },
        "selectedProductId": {
          "type": [
            "string",
            "null"
          ]
        },
        "alternateProductId": {
          "type": [
            "string",
            "null"
          ]
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ]
        },
        "ranking": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "productId",
              "rationaleCodes"
            ],
            "properties": {
              "productId": {
                "type": "string"
              },
              "rationaleCodes": {
                "type": "array",
                "minItems": 1,
                "maxItems": 3,
                "items": {
                  "type": "string",
                  "enum": [
                    "strongest_need_fit",
                    "catalog_truth_leader",
                    "quality_leader",
                    "budget_fit",
                    "returns_strength",
                    "balanced_choice"
                  ]
                }
              }
            }
          }
        },
        "verification": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "hardConstraintsAppliedBeforeModel",
            "candidateSetPreserved",
            "checkoutDataSharedWithModel",
            "sponsorshipSharedWithModel",
            "freeformClaimsAllowed"
          ],
          "properties": {
            "hardConstraintsAppliedBeforeModel": {
              "type": "boolean",
              "const": true
            },
            "candidateSetPreserved": {
              "type": "boolean",
              "const": true
            },
            "checkoutDataSharedWithModel": {
              "type": "boolean",
              "const": false
            },
            "sponsorshipSharedWithModel": {
              "type": "boolean",
              "const": false
            },
            "freeformClaimsAllowed": {
              "type": "boolean",
              "const": false
            }
          }
        },
        "fallbackReason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "not_configured",
            "no_eligible_products",
            "provider_error",
            "timeout",
            "invalid_model_output",
            null
          ]
        },
        "retention": {
          "type": "string",
          "const": "not-stored"
        }
      }
    },
    "CommerceDiscoveryReport": {
      "type": "object",
      "description": "Constitution-constrained deterministic discovery result over caller-supplied candidates.",
      "required": [
        "schema",
        "need",
        "evaluatedAt",
        "constitution",
        "rankingPolicy",
        "catalogProvenance",
        "matches",
        "rejected",
        "retention"
      ],
      "properties": {
        "schema": {
          "type": "string",
          "const": "agentpay.product-discovery/1.1"
        },
        "need": {
          "type": "string"
        },
        "evaluatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "constitution": {
          "$ref": "#/$defs/BuyerConstitution"
        },
        "rankingPolicy": {
          "type": "object",
          "properties": {
            "paidPlacementChangesOrganicRank": {
              "type": "boolean",
              "const": false
            },
            "hardFilters": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "weights": {
              "type": "object",
              "additionalProperties": {
                "type": "number"
              }
            }
          }
        },
        "catalogProvenance": {
          "type": "object",
          "required": [
            "source",
            "merchantConnection",
            "warning"
          ],
          "properties": {
            "source": {
              "type": "string",
              "const": "caller_supplied_candidates"
            },
            "merchantConnection": {
              "type": "string",
              "const": "not_verified"
            },
            "warning": {
              "type": "string"
            }
          }
        },
        "matches": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "product",
              "fitScore",
              "rank",
              "reasons",
              "disclosure",
              "attributionDraft"
            ],
            "properties": {
              "product": {
                "$ref": "#/$defs/CommerceProductCandidate"
              },
              "fitScore": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "rank": {
                "type": "integer",
                "minimum": 1
              },
              "reasons": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "enum": [
                        "NEED_FIT",
                        "CATALOG_TRUTH",
                        "QUALITY",
                        "BUDGET_FIT",
                        "RETURNS"
                      ]
                    },
                    "score": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 100
                    }
                  }
                }
              },
              "disclosure": {
                "type": "string",
                "enum": [
                  "organic",
                  "sponsored"
                ]
              },
              "attributionDraft": {
                "type": "object",
                "description": "Non-binding draft; merchant agreement and verified conversion webhook are required.",
                "additionalProperties": true
              }
            }
          }
        },
        "rejected": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "productId": {
                "type": "string"
              },
              "reasonCodes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "retention": {
          "type": "string",
          "const": "not-stored"
        }
      }
    },
    "CommerceProductCandidate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "merchantId",
        "merchantName",
        "title",
        "category",
        "priceMinor",
        "currency",
        "availability",
        "checkoutUrl",
        "imageUrl",
        "deliveryDays",
        "returnWindowDays",
        "refundable",
        "catalogUpdatedAt",
        "truthScore",
        "qualityScore",
        "needSignals"
      ],
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 200
        },
        "merchantId": {
          "type": "string",
          "maxLength": 200
        },
        "merchantName": {
          "type": "string",
          "maxLength": 300
        },
        "title": {
          "type": "string",
          "maxLength": 500
        },
        "category": {
          "type": "string",
          "maxLength": 120,
          "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$"
        },
        "priceMinor": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000000000
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Za-z]{3}$"
        },
        "availability": {
          "type": "string",
          "enum": [
            "in_stock",
            "out_of_stock",
            "preorder",
            "backorder"
          ]
        },
        "checkoutUrl": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://"
        },
        "imageUrl": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://"
        },
        "deliveryDays": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3650
        },
        "returnWindowDays": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3650
        },
        "refundable": {
          "type": "boolean"
        },
        "catalogUpdatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "truthScore": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "qualityScore": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "needSignals": {
          "type": "array",
          "minItems": 1,
          "maxItems": 30,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "need",
              "score"
            ],
            "properties": {
              "need": {
                "type": "string",
                "maxLength": 80
              },
              "score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        },
        "sponsored": {
          "type": "boolean",
          "default": false
        }
      }
    },
    "SignedPacketSignature": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "algorithm",
        "keyId",
        "value"
      ],
      "properties": {
        "algorithm": {
          "type": "string",
          "const": "HMAC-SHA256"
        },
        "keyId": {
          "type": "string",
          "const": "agentpay-commerce-compiler-v1"
        },
        "value": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      }
    }
  }
}