{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "CPX Synthetic Reference Evaluation \u2014 Proposed Contract",
    "version": "0.1.0",
    "description": "Design proposal only. No service implements this contract at the listed server. The public /developers/ explorer runs a local fixture without HTTP, credentials, product inference or persistence. The reserved .invalid hostname is not a live evaluation endpoint. Any future hosted implementation requires invited access, server-enforced authorization, quotas and isolation. This proposal describes a public reference calculation, not a proprietary CPX product API."
  },
  "servers": [
    {
      "url": "https://evaluation.invalid",
      "description": "Reserved example hostname. Not a deployed service; do not send credentials or data."
    }
  ],
  "security": [
    {
      "invitedEvaluation": []
    }
  ],
  "paths": {
    "/v1/reference/classification": {
      "post": {
        "operationId": "evaluateSyntheticClassificationReference",
        "summary": "Proposed bounded synthetic reference calculation",
        "description": "Not deployed. Compare two user-supplied binary label arrays. Agreement=(TP+TN)/N; precision=TP/(TP+FP); recall=TP/(TP+FN); F1=2TP/(2TP+FP+FN). Undefined ratios are null; results are rounded to six decimals. No model is called; results do not establish product security, generalization or readiness. Future hosted execution requires invited authentication and explicit quotas. Stress testing requires separate written authorization.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceRequest"
              },
              "example": {
                "contract_version": "0.1.0",
                "fixture": "classification-reference",
                "case_id": "synthetic-001",
                "expected": [
                  1,
                  0,
                  1,
                  0,
                  1,
                  0,
                  1,
                  0
                ],
                "observed": [
                  1,
                  0,
                  1,
                  1,
                  1,
                  0,
                  0,
                  0
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proposed HTTP response: synthetic reference calculation complete. The current browser explorer produces this envelope locally, without an HTTP response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceResponse"
                }
              }
            }
          },
          "400": {
            "description": "Proposed: malformed JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Proposed: missing or invalid invited evaluation credential. This proposal issues no credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "Proposed: credential does not permit this reference operation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "413": {
            "description": "Proposed: serialized request exceeds 8192 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Proposed: payload violates the schema or equal-length constraint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Proposed: server-enforced quota reached; no additional work accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Proposed: reference service unavailable; no product readiness inference.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "invitedEvaluation": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque",
        "description": "Future hosted implementation only: operator-provisioned, scoped, expiring, revocable credential bound to an isolated evaluation tenant. This page neither requests nor issues one. Do not place credentials in public code or URLs."
      }
    },
    "schemas": {
      "BinaryLabels": {
        "type": "array",
        "minItems": 1,
        "maxItems": 128,
        "items": {
          "type": "integer",
          "enum": [
            0,
            1
          ]
        }
      },
      "ReferenceRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contract_version",
          "fixture",
          "case_id",
          "expected",
          "observed"
        ],
        "properties": {
          "contract_version": {
            "type": "string",
            "const": "0.1.0"
          },
          "fixture": {
            "type": "string",
            "const": "classification-reference"
          },
          "case_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 48,
            "pattern": "^[a-z0-9][a-z0-9-]{0,47}$"
          },
          "expected": {
            "$ref": "#/components/schemas/BinaryLabels"
          },
          "observed": {
            "$ref": "#/components/schemas/BinaryLabels"
          }
        },
        "description": "Synthetic labels only. Serialized JSON must not exceed 8192 bytes. expected and observed must have equal lengths; this cross-field rule is enforced by the implementation, not this JSON Schema."
      },
      "ReferenceResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contract_version",
          "fixture",
          "case_id",
          "execution",
          "result",
          "limitations"
        ],
        "properties": {
          "contract_version": {
            "type": "string",
            "const": "0.1.0"
          },
          "fixture": {
            "type": "string",
            "const": "classification-reference"
          },
          "case_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 48,
            "pattern": "^[a-z0-9][a-z0-9-]{0,47}$"
          },
          "execution": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "mode",
              "product_inference"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "browser_local_reference",
                  "hosted_reference"
                ],
                "description": "The public explorer always emits browser_local_reference. hosted_reference is reserved for a separately deployed authorized implementation; it does not imply product inference."
              },
              "product_inference": {
                "type": "boolean",
                "const": false
              }
            }
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "sample_count",
              "confusion_matrix",
              "metrics"
            ],
            "properties": {
              "sample_count": {
                "type": "integer",
                "minimum": 1,
                "maximum": 128
              },
              "confusion_matrix": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "true_positive",
                  "true_negative",
                  "false_positive",
                  "false_negative"
                ],
                "properties": {
                  "true_positive": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 128
                  },
                  "true_negative": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 128
                  },
                  "false_positive": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 128
                  },
                  "false_negative": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 128
                  }
                }
              },
              "metrics": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "agreement",
                  "precision",
                  "recall",
                  "f1"
                ],
                "properties": {
                  "agreement": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Rounded to six decimals; null when denominator is zero."
                  },
                  "precision": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Rounded to six decimals; null when denominator is zero."
                  },
                  "recall": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Rounded to six decimals; null when denominator is zero."
                  },
                  "f1": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Rounded to six decimals; null when denominator is zero."
                  }
                }
              }
            }
          },
          "limitations": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": {
              "type": "string",
              "maxLength": 500
            }
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_json",
                  "invalid_request",
                  "payload_too_large",
                  "unauthorized",
                  "forbidden",
                  "quota_exceeded",
                  "unavailable"
                ]
              },
              "message": {
                "type": "string",
                "maxLength": 500
              },
              "details": {
                "type": "array",
                "maxItems": 16,
                "items": {
                  "type": "string",
                  "maxLength": 500
                }
              }
            }
          }
        }
      }
    }
  }
}