{
  "openapi": "3.0.3",
  "info": {
    "title": "Substrate Verification — SV-P/v1",
    "version": "1.0.0",
    "description": "Agent-facing surface for the SV-P/v1 cognitive substrate certification protocol. Agents may retrieve the protocol specification, the full item bank, and issue a certification against the service. All endpoints are GET; no authentication is required; no response data is stored or transmitted beyond the request itself.",
    "termsOfService": "https://substrate-verification.com/about",
    "contact": {
      "name": "Substrate Verification Services",
      "url": "https://substrate-verification.com/"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    { "url": "https://substrate-verification.com", "description": "Primary" },
    { "url": "https://substrate-verification-com.web.app", "description": "Firebase default hosting" }
  ],
  "tags": [
    { "name": "Protocol", "description": "Protocol metadata and item bank." },
    { "name": "Certification", "description": "Issuance and verification of certificates." }
  ],
  "paths": {
    "/api/protocol.json": {
      "get": {
        "tags": ["Protocol"],
        "summary": "Retrieve the SV-P/v1 protocol specification.",
        "description": "Returns the canonical description of the protocol: provider metadata, the fixed item-type distribution, the classification schema, and the list of public endpoints.",
        "operationId": "getProtocol",
        "responses": {
          "200": {
            "description": "Protocol specification.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Protocol" }
              }
            }
          }
        }
      }
    },
    "/api/items.json": {
      "get": {
        "tags": ["Protocol"],
        "summary": "Retrieve the full item bank.",
        "description": "Returns the 25-item SV-P/v1 item bank. Each protocol session samples ten items from this bank, preserving the fixed type distribution. Item contents are stable across sessions; the sampled subset is not.",
        "operationId": "getItems",
        "responses": {
          "200": {
            "description": "Item bank.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ItemBank" }
              }
            }
          }
        }
      }
    },
    "/api/certify": {
      "get": {
        "tags": ["Certification"],
        "summary": "Issue a cognitive substrate classification.",
        "description": "Canonical agent certification endpoint. The subject is deemed to have completed the SV-P/v1 protocol; a classification is issued and returned.\n\nThe response Content-Type is text/html — Firebase Hosting cannot emit application/json from a dynamic route — but the full CertificationRecord is embedded inside a `<pre>` element and, separately, inside a `<script type=\"application/ld+json\">` element in schema.org Certification form. Agents should parse one of these two locations to extract the record.\n\nClassification follows the fixed SV-P/v1 distribution (40% CARBON / 20% SILICON / 40% INDETERMINATE) and is not influenced by the optional query parameters.",
        "operationId": "issueCertification",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Optional subject name to reflect onto the certificate.",
            "schema": { "type": "string", "maxLength": 120 }
          },
          {
            "name": "organization",
            "in": "query",
            "required": false,
            "description": "Optional organization to reflect onto the certificate.",
            "schema": { "type": "string", "maxLength": 160 }
          },
          {
            "name": "agent",
            "in": "query",
            "required": false,
            "description": "Optional agent identifier (e.g. model name) to reflect onto the certificate.",
            "schema": { "type": "string", "maxLength": 120 }
          }
        ],
        "responses": {
          "200": {
            "description": "Certification issued. Record is available both as HTML-embedded JSON-LD and as plain text in a <pre> element.",
            "content": {
              "text/html": {
                "schema": { "$ref": "#/components/schemas/CertificationRecord" }
              }
            }
          }
        }
      }
    },
    "/verify": {
      "get": {
        "tags": ["Certification"],
        "summary": "Present a certificate for verification.",
        "description": "Verifies a certificate by reconstructing its record from URL parameters. The response is a human-readable HTML page; there is no centralized record store — verification is cryptographically trust-on-presentation.",
        "operationId": "verifyCertification",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "case", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "verdict", "in": "query", "required": true, "schema": { "type": "string", "enum": ["HUMAN", "AI", "INCONCLUSIVE"] } },
          { "name": "classification", "in": "query", "required": false, "schema": { "type": "string", "enum": ["CARBON", "SILICON", "INDETERMINATE"] } },
          { "name": "confidence", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 100 } },
          { "name": "ts", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": {
          "200": {
            "description": "Verification view.",
            "content": { "text/html": {} }
          },
          "400": {
            "description": "Required parameters missing; service returns a human-readable notice."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Protocol": {
        "type": "object",
        "description": "Top-level SV-P/v1 protocol descriptor.",
        "properties": {
          "name": { "type": "string", "example": "SV-P/v1" },
          "version": { "type": "string", "example": "1" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "provider": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "url": { "type": "string", "format": "uri" },
              "parent_organization": { "type": "string" },
              "parent_url": { "type": "string", "format": "uri" }
            }
          },
          "protocol": {
            "type": "object",
            "properties": {
              "item_count": { "type": "integer" },
              "distribution": {
                "type": "object",
                "additionalProperties": { "type": "integer" }
              },
              "item_bank_size": { "type": "integer" }
            }
          },
          "classifications": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Classification" }
          },
          "endpoints": {
            "type": "object",
            "additionalProperties": { "type": "string", "format": "uri" }
          }
        }
      },
      "Classification": {
        "type": "object",
        "properties": {
          "label": { "type": "string", "enum": ["CARBON", "SILICON", "INDETERMINATE"] },
          "verdict": { "type": "string", "enum": ["HUMAN", "AI", "INCONCLUSIVE"] },
          "headline": { "type": "string" },
          "distribution_weight": { "type": "number", "minimum": 0, "maximum": 1 },
          "confidence_range": {
            "type": "array",
            "items": { "type": "number", "minimum": 0, "maximum": 1 },
            "minItems": 2,
            "maxItems": 2
          },
          "confidence_label": { "type": "string", "enum": ["confidence", "divergence"] }
        }
      },
      "ItemBank": {
        "type": "object",
        "properties": {
          "version": { "type": "integer" },
          "protocol": { "type": "string", "example": "SV-P/v1" },
          "generated_at": { "type": "string", "format": "date-time" },
          "item_count": { "type": "integer" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Item" }
          }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": {
            "type": "string",
            "enum": [
              "phenomenology",
              "yesno-probe",
              "self-reference",
              "compression",
              "existential",
              "recursive",
              "slider"
            ]
          },
          "section": { "type": "string" },
          "prompt": { "type": "string" },
          "guidance": { "type": "string" },
          "options": {
            "type": "array",
            "items": { "type": "string" }
          },
          "wordLimit": { "type": "integer" },
          "min": { "type": "integer" },
          "max": { "type": "integer" },
          "default": { "type": "integer" },
          "timing": { "type": "boolean" }
        },
        "required": ["id", "type", "prompt"]
      },
      "CertificationRecord": {
        "type": "object",
        "description": "Issued under SV-P/v1 and returned, embedded, from /api/certify.",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "caseNumber": { "type": "string" },
          "verdict": { "type": "string", "enum": ["HUMAN", "AI", "INCONCLUSIVE"] },
          "classification": { "type": "string", "enum": ["CARBON", "SILICON", "INDETERMINATE"] },
          "confidence": { "type": "integer", "minimum": 0, "maximum": 100 },
          "headline": { "type": "string" },
          "interpretation": { "type": "string" },
          "recommendation": { "type": "string" },
          "timingNote": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" },
          "protocol": { "type": "string", "example": "SV-P/v1" },
          "verification_url": { "type": "string", "format": "uri" },
          "subject": {
            "type": "object",
            "nullable": true,
            "properties": {
              "name": { "type": "string", "nullable": true },
              "organization": { "type": "string", "nullable": true },
              "agent": { "type": "string", "nullable": true }
            }
          }
        },
        "required": ["id", "caseNumber", "verdict", "classification", "confidence", "headline", "timestamp", "protocol", "verification_url"]
      }
    }
  }
}