{
  "openapi": "3.1.0",
  "info": {
    "title": "JRS Review Engine API",
    "version": "0.1.0-validation",
    "description": "Current contract for POST /api/v1/review-engine. The endpoint evaluates one record against five Review Engine condition keys. An authenticated caller may explicitly request a development Decision Reconstruction Manifest. This is an unvalidated, single-model system in operational validation. Reproducibility is distinct from accuracy and validation."
  },
  "servers": [
    {
      "url": "https://www.jrsstandard.com"
    }
  ],
  "paths": {
    "/api/v1/review-engine": {
      "post": {
        "summary": "Review a record against the five JRS conditions",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewRequest"
              },
              "example": {
                "text": "On March 4, 11, and 18 the weekly report was submitted after the Friday 5:00 PM deadline (shared-drive timestamps). On March 20 the manager met with the employee; notes are on file.",
                "runs": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Review result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewResponse"
                }
              }
            }
          },
          "400": {
            "description": "invalid_json | record_too_short",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {
            "description": "unauthorized. Returned when a valid bearer credential is required and is not presented.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {
            "description": "method_not_allowed",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {
            "description": "rate_limited (best-effort, per-instance, per-IP)",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "502": {
            "description": "review_failed (model or parse error)",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "engine_not_configured",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          }
        },
        "x-jrs-condition-vocabulary": "review_engine_keys",
        "x-jrs-routing-vocabulary": "engine_determination",
        "x-jrs-manifest-output": "optional_authenticated_development_artifact"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A valid bearer credential is required for controlled access. Evaluation access is provided through the written enterprise process."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "method_not_allowed",
              "engine_not_configured",
              "unauthorized",
              "rate_limited",
              "invalid_json",
              "record_too_short",
              "review_failed"
            ]
          },
          "detail": {"type": "string"}
        },
        "required": ["error"],
        "additionalProperties": false
      },
      "ReviewRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 40,
            "description": "The record under review. Inputs longer than 8,000 characters are accepted but truncated to the first 8,000 characters before evaluation."
          },
          "runs": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "default": 1,
            "description": "Number of independent runs. runs>1 returns a disclosed variance block."
          },
          "include_manifest": {
            "type": "boolean",
            "default": false,
            "description": "Authenticated opt-in. Returns an unsigned development Manifest as an additional response field. An open-sandbox caller cannot request it. The output can contain record-derived notes and must be protected by the caller."
          }
        },
        "additionalProperties": false
      },
      "ConditionResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "review",
              "gap"
            ]
          },
          "note": {
            "type": "string",
            "maxLength": 400
          }
        },
        "required": [
          "status",
          "note"
        ],
        "additionalProperties": false
      },
      "ReviewResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "api_version": {
            "type": "string",
            "const": "v1"
          },
          "engine": {
            "type": "string",
            "const": "JRS Review Engine"
          },
          "engine_version": {
            "type": "string",
            "const": "0.1.0-validation"
          },
          "model": {
            "type": "string"
          },
          "evidence_stage": {
            "type": "string",
            "example": "operational_validation",
            "const": "operational_validation"
          },
          "disclaimer": {
            "type": "string"
          },
          "reviewed_at": {
            "type": "string",
            "format": "date-time"
          },
          "runs": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          "manifest": {
            "type": "object",
            "description": "Optional only when include_manifest=true on an authenticated request. Conforms to schemas/jrs-decision-reconstruction-manifest.schema.json. Its hash is self-consistent, not an authenticated signature. The artifact can contain record-derived notes.",
            "x-jrs-schema": "/schemas/jrs-decision-reconstruction-manifest.schema.json"
          },
          "result": {
            "type": "object",
            "properties": {
              "conditions": {
                "type": "object",
                "properties": {
                  "basis_identification": {
                    "$ref": "#/components/schemas/ConditionResult"
                  },
                  "reasoning_traceability": {
                    "$ref": "#/components/schemas/ConditionResult"
                  },
                  "cold_reviewer_clarity": {
                    "$ref": "#/components/schemas/ConditionResult"
                  },
                  "accountability_support": {
                    "$ref": "#/components/schemas/ConditionResult"
                  },
                  "temporal_reconstructability": {
                    "$ref": "#/components/schemas/ConditionResult"
                  }
                },
                "required": [
                  "basis_identification",
                  "reasoning_traceability",
                  "cold_reviewer_clarity",
                  "accountability_support",
                  "temporal_reconstructability"
                ],
                "additionalProperties": false
              },
              "determination": {
                "type": "string",
                "enum": [
                  "ready",
                  "review_required",
                  "gap_identified"
                ]
              },
              "remediation_note": {
                "type": "string",
                "maxLength": 600
              },
              "finding": {
                "type": "object",
                "properties": {
                  "ai_function": {
                    "type": "string",
                    "enum": [
                      "summarization",
                      "recommendation",
                      "analysis",
                      "narrative",
                      ""
                    ]
                  },
                  "condition_triggered": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "determination": {
                    "type": "string",
                    "enum": [
                      "ready",
                      "review_required",
                      "gap_identified"
                    ]
                  },
                  "compliant_version": {
                    "type": "string",
                    "maxLength": 600
                  }
                },
                "required": [
                  "ai_function",
                  "condition_triggered",
                  "determination",
                  "compliant_version"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "conditions",
              "determination",
              "remediation_note",
              "finding"
            ],
            "additionalProperties": false
          },
          "variance": {
            "type": "object",
            "description": "Present only when runs is greater than 1. Reports run-to-run agreement and does not establish accuracy or validation.",
            "properties": {
              "per_condition": {
                "type": "object",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "modal": {
                      "type": "string",
                      "enum": [
                        "pass",
                        "review",
                        "gap"
                      ]
                    },
                    "agreement": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    }
                  },
                  "required": [
                    "modal",
                    "agreement"
                  ],
                  "additionalProperties": false
                }
              },
              "overall_consistency": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "runs_detail": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            },
            "required": [
              "per_condition",
              "overall_consistency",
              "runs_detail"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "request_id",
          "api_version",
          "engine",
          "engine_version",
          "model",
          "evidence_stage",
          "disclaimer",
          "reviewed_at",
          "runs",
          "result"
        ],
        "additionalProperties": false
      }
    }
  },
  "externalDocs": {
    "description": "Decision Reconstruction Manifest v1.0 public package",
    "url": "https://www.jrsstandard.com/manifest.html"
  }
}