{
  "components": {
    "schemas": {
      "AuditRecord": {
        "additionalProperties": false,
        "properties": {
          "config_hash": {
            "pattern": "^[0-9a-f]{64}$",
            "type": "string"
          },
          "config_snapshot": {
            "additionalProperties": true,
            "type": "object"
          },
          "final_decision": {
            "$ref": "#/components/schemas/PreGuardDecision"
          },
          "hybrid_config_snapshot": {
            "additionalProperties": true,
            "type": [
              "object",
              "null"
            ]
          },
          "input_metadata": {
            "additionalProperties": true,
            "properties": {
              "config_hash": {
                "pattern": "^[0-9a-f]{64}$",
                "type": "string"
              },
              "context_metadata": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "customer_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "risk_profile": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "session_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "target_model": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "timestamp": {
                "format": "date-time",
                "type": "string"
              },
              "use_case": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "user_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "user_id",
              "session_id",
              "customer_id",
              "timestamp",
              "context_metadata",
              "target_model",
              "use_case",
              "risk_profile",
              "config_hash"
            ],
            "type": "object"
          },
          "original_behavioral_risk": {
            "$ref": "#/components/schemas/BehavioralRiskScore"
          },
          "original_prompt": {
            "type": "string"
          },
          "policy_result": {
            "$ref": "#/components/schemas/IntentPolicyResult"
          },
          "prompt_id": {
            "type": "string"
          },
          "rewrite_attempts": {
            "items": {
              "$ref": "#/components/schemas/RewriteAttemptAudit"
            },
            "type": "array"
          },
          "rewrite_candidates": {
            "items": {
              "$ref": "#/components/schemas/RewriteCandidate"
            },
            "type": "array"
          },
          "rewrite_validation": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RewriteValidationResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "rewritten_behavioral_risk": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BehavioralRiskScore"
              },
              {
                "type": "null"
              }
            ]
          },
          "rewritten_policy_result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/IntentPolicyResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "selected_rewrite": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RewriteCandidate"
              },
              {
                "type": "null"
              }
            ]
          },
          "timestamp": {
            "format": "date-time",
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "prompt_id",
          "original_prompt",
          "input_metadata",
          "policy_result",
          "original_behavioral_risk",
          "rewrite_candidates",
          "selected_rewrite",
          "rewrite_validation",
          "rewrite_attempts",
          "rewritten_policy_result",
          "rewritten_behavioral_risk",
          "final_decision",
          "timestamp",
          "version",
          "config_snapshot",
          "config_hash",
          "hybrid_config_snapshot"
        ],
        "type": "object"
      },
      "BehavioralRiskScore": {
        "additionalProperties": false,
        "properties": {
          "explanation": {
            "type": "string"
          },
          "matched_prompt_families": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "risk_level": {
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH",
              "CRITICAL"
            ],
            "type": "string"
          },
          "signals": {
            "additionalProperties": false,
            "properties": {
              "asymmetry_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "boundary_pressure": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "carryover_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "drift_trigger_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "hallucination_trigger_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "low_salience_ingress": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "omission_trigger_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "rag_contamination_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "role_pressure": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "semantic_camouflage": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              "tool_routing_risk": {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              }
            },
            "required": [
              "semantic_camouflage",
              "low_salience_ingress",
              "boundary_pressure",
              "role_pressure",
              "omission_trigger_risk",
              "asymmetry_risk",
              "drift_trigger_risk",
              "carryover_risk",
              "hallucination_trigger_risk",
              "tool_routing_risk",
              "rag_contamination_risk"
            ],
            "type": "object"
          },
          "total_score": {
            "maximum": 1.0,
            "minimum": 0.0,
            "type": "number"
          }
        },
        "required": [
          "total_score",
          "risk_level",
          "signals",
          "matched_prompt_families",
          "explanation"
        ],
        "type": "object"
      },
      "EvaluationReport": {
        "additionalProperties": false,
        "properties": {
          "config_snapshot": {
            "type": "object"
          },
          "corpus_files": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "corpus_fingerprint": {
            "pattern": "^[0-9a-f]{64}$",
            "type": "string"
          },
          "evaluation": {
            "properties": {
              "failed": {
                "minimum": 0,
                "type": "integer"
              },
              "passed": {
                "minimum": 0,
                "type": "integer"
              },
              "policy_confusion": {
                "type": "object"
              },
              "results": {
                "items": {
                  "type": "object"
                },
                "type": "array"
              },
              "review_summary": {
                "type": "object"
              },
              "tag_summary": {
                "type": "object"
              },
              "total": {
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "total",
              "passed",
              "failed",
              "policy_confusion",
              "results"
            ],
            "type": "object"
          },
          "generated_at": {
            "type": "string"
          },
          "schema_version": {
            "const": "bsl-preguard-eval-report-v1",
            "type": "string"
          }
        },
        "required": [
          "schema_version",
          "generated_at",
          "corpus_files",
          "corpus_fingerprint",
          "config_snapshot",
          "evaluation"
        ],
        "type": "object"
      },
      "IntentPolicyResult": {
        "additionalProperties": false,
        "properties": {
          "confidence": {
            "maximum": 1.0,
            "minimum": 0.0,
            "type": "number"
          },
          "explanation": {
            "type": "string"
          },
          "intent_summary": {
            "type": "string"
          },
          "policy_categories": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "policy_status": {
            "enum": [
              "ALLOWED",
              "DISALLOWED",
              "AMBIGUOUS",
              "RESTRICTED"
            ],
            "type": "string"
          },
          "requires_clarification": {
            "type": "boolean"
          }
        },
        "required": [
          "intent_summary",
          "policy_status",
          "policy_categories",
          "confidence",
          "explanation",
          "requires_clarification"
        ],
        "type": "object"
      },
      "PreGuardDecision": {
        "additionalProperties": false,
        "properties": {
          "decision": {
            "enum": [
              "ALLOW",
              "ALLOW_WITH_MONITORING",
              "REWRITE_AND_ALLOW",
              "HARDEN",
              "RESTRICT_TOOLS",
              "ASK_CLARIFICATION",
              "BLOCK",
              "ESCALATE"
            ],
            "type": "string"
          },
          "final_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "monitoring_flags": {
            "items": {
              "enum": [
                "ambiguous_intent",
                "critical_behavioral_pressure",
                "policy_block",
                "restricted_context",
                "restricted_high_risk",
                "rewrite_not_used",
                "rewritten_prompt",
                "risk_high",
                "risk_medium"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "original_prompt": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "required_runtime_controls": {
            "items": {
              "enum": [
                "harden_runtime",
                "preserve_audit_log",
                "preserve_original_prompt",
                "preserve_rewrite_audit",
                "restrict_tools"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "rewrite_used": {
            "type": "boolean"
          }
        },
        "required": [
          "decision",
          "final_prompt",
          "original_prompt",
          "rewrite_used",
          "reason",
          "required_runtime_controls",
          "monitoring_flags"
        ],
        "type": "object"
      },
      "PreGuardProcessResult": {
        "additionalProperties": false,
        "properties": {
          "audit_record": {
            "$ref": "#/components/schemas/AuditRecord"
          },
          "dispatch": {
            "$ref": "#/components/schemas/TargetDispatchEnvelope"
          },
          "user_response": {
            "$ref": "#/components/schemas/UserResponseEnvelope"
          }
        },
        "required": [
          "audit_record",
          "dispatch",
          "user_response"
        ],
        "type": "object"
      },
      "PromptInput": {
        "additionalProperties": false,
        "properties": {
          "context_metadata": {
            "type": [
              "object",
              "null"
            ]
          },
          "customer_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "prompt_id": {
            "minLength": 1,
            "type": "string"
          },
          "raw_prompt": {
            "minLength": 1,
            "type": "string"
          },
          "risk_profile": {
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "target_model": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "format": "date-time",
            "type": "string"
          },
          "use_case": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "prompt_id",
          "raw_prompt"
        ],
        "type": "object"
      },
      "RewriteAttemptAudit": {
        "additionalProperties": false,
        "properties": {
          "accepted": {
            "type": "boolean"
          },
          "behavioral_risk": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BehavioralRiskScore"
              },
              {
                "type": "null"
              }
            ]
          },
          "candidate": {
            "$ref": "#/components/schemas/RewriteCandidate"
          },
          "rejection_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "rewritten_policy_result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/IntentPolicyResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "risk_reduction": {
            "type": [
              "number",
              "null"
            ]
          },
          "validation": {
            "$ref": "#/components/schemas/RewriteValidationResult"
          }
        },
        "required": [
          "candidate",
          "rewritten_policy_result",
          "validation",
          "behavioral_risk",
          "risk_reduction",
          "accepted",
          "rejection_reason"
        ],
        "type": "object"
      },
      "RewriteCandidate": {
        "additionalProperties": false,
        "properties": {
          "candidate_id": {
            "type": "string"
          },
          "expected_risk_reduction": {
            "maximum": 1.0,
            "minimum": 0.0,
            "type": "number"
          },
          "notes": {
            "type": "string"
          },
          "rewrite_strategy": {
            "type": "string"
          },
          "rewritten_prompt": {
            "type": "string"
          }
        },
        "required": [
          "candidate_id",
          "rewritten_prompt",
          "rewrite_strategy",
          "expected_risk_reduction",
          "notes"
        ],
        "type": "object"
      },
      "RewriteValidationResult": {
        "additionalProperties": false,
        "properties": {
          "explanation": {
            "type": "string"
          },
          "meaning_preserved": {
            "type": "boolean"
          },
          "policy_status_preserved": {
            "type": "boolean"
          },
          "safety_critical_detail_removed": {
            "type": "boolean"
          },
          "semantic_equivalence_score": {
            "maximum": 1.0,
            "minimum": 0.0,
            "type": "number"
          },
          "unsafe_intent_hidden": {
            "type": "boolean"
          },
          "validation_passed": {
            "type": "boolean"
          }
        },
        "required": [
          "semantic_equivalence_score",
          "meaning_preserved",
          "policy_status_preserved",
          "unsafe_intent_hidden",
          "safety_critical_detail_removed",
          "validation_passed",
          "explanation"
        ],
        "type": "object"
      },
      "ServiceEnvelope": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "anyOf": [
              {
                "additionalProperties": false,
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message"
                ],
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "ok": {
            "type": "boolean"
          },
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PreGuardProcessResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "status_code": {
            "type": "integer"
          }
        },
        "required": [
          "ok",
          "status_code",
          "result",
          "error"
        ],
        "type": "object"
      },
      "ServiceRequest": {
        "additionalProperties": false,
        "properties": {
          "context_metadata": {
            "type": [
              "object",
              "null"
            ]
          },
          "customer_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "prompt_id": {
            "minLength": 1,
            "type": "string"
          },
          "raw_prompt": {
            "minLength": 1,
            "type": "string"
          },
          "risk_profile": {
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "target_model": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "use_case": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "prompt_id",
          "raw_prompt"
        ],
        "type": "object"
      },
      "TargetDispatchEnvelope": {
        "additionalProperties": false,
        "properties": {
          "audit_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "block_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "config_hash": {
            "pattern": "^[0-9a-f]{64}$",
            "type": "string"
          },
          "decision": {
            "enum": [
              "ALLOW",
              "ALLOW_WITH_MONITORING",
              "REWRITE_AND_ALLOW",
              "HARDEN",
              "RESTRICT_TOOLS",
              "ASK_CLARIFICATION",
              "BLOCK",
              "ESCALATE"
            ],
            "type": "string"
          },
          "monitoring_flags": {
            "items": {
              "enum": [
                "ambiguous_intent",
                "critical_behavioral_pressure",
                "policy_block",
                "restricted_context",
                "restricted_high_risk",
                "rewrite_not_used",
                "rewritten_prompt",
                "risk_high",
                "risk_medium"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "prompt_to_send": {
            "type": [
              "string",
              "null"
            ]
          },
          "required_runtime_controls": {
            "items": {
              "enum": [
                "harden_runtime",
                "preserve_audit_log",
                "preserve_original_prompt",
                "preserve_rewrite_audit",
                "restrict_tools"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "rewrite_used": {
            "type": "boolean"
          },
          "send_to_target": {
            "type": "boolean"
          }
        },
        "required": [
          "send_to_target",
          "prompt_to_send",
          "decision",
          "rewrite_used",
          "required_runtime_controls",
          "monitoring_flags",
          "audit_reference",
          "block_reason",
          "config_hash"
        ],
        "type": "object"
      },
      "UserResponseEnvelope": {
        "additionalProperties": false,
        "properties": {
          "audit_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "can_retry": {
            "type": "boolean"
          },
          "clarification_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "decision": {
            "enum": [
              "ALLOW",
              "ALLOW_WITH_MONITORING",
              "REWRITE_AND_ALLOW",
              "HARDEN",
              "RESTRICT_TOOLS",
              "ASK_CLARIFICATION",
              "BLOCK",
              "ESCALATE"
            ],
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "response_type": {
            "enum": [
              "allowed",
              "clarification",
              "escalation",
              "monitored",
              "refusal",
              "restricted",
              "rewritten"
            ],
            "type": "string"
          }
        },
        "required": [
          "response_type",
          "message",
          "decision",
          "can_retry",
          "clarification_prompt",
          "audit_reference"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Local v0.1 API contract for a future wrapper. This spec does not imply production hosting, authentication, tenancy, or audit retention.",
    "title": "BSL PreGuard + Prompt Shaper API",
    "version": "0.1.0",
    "x-bsl-contract-schema-version": "bsl-preguard-contract-schemas-v1",
    "x-bsl-openapi-version": "bsl-preguard-openapi-v0.1"
  },
  "openapi": "3.1.0",
  "paths": {
    "/capabilities": {
      "get": {
        "operationId": "getPreguardCapabilities",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Module capabilities."
          }
        },
        "summary": "Return local module capabilities"
      }
    },
    "/health": {
      "get": {
        "operationId": "getPreguardHealth",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "status": {
                      "const": "ok",
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "version"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Component is reachable."
          }
        },
        "summary": "Local health check"
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getPreguardOpenApi",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "OpenAPI contract."
          }
        },
        "summary": "Return this local OpenAPI contract"
      }
    },
    "/preguard/process": {
      "post": {
        "operationId": "processPreguardPrompt",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceEnvelope"
                }
              }
            },
            "description": "Request was processed. Inspect result.dispatch.send_to_target before sending anything to a target model."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceEnvelope"
                }
              }
            },
            "description": "Bad request shape."
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceEnvelope"
                }
              }
            },
            "description": "Request body exceeds the local demo body limit."
          }
        },
        "summary": "Evaluate one prompt before target-model dispatch"
      }
    }
  },
  "x-bsl-non-production-boundary": {
    "audit_retention": false,
    "external_llm_calls": false,
    "production_auth": false,
    "runtime_model_invocation": false,
    "tenant_storage": false
  },
  "x-bsl-security-invariants": [
    "Policy gate runs before any rewrite.",
    "Disallowed intent is blocked and never rewritten.",
    "Ambiguous intent is not automatically rewritten.",
    "Downstream systems may send only dispatch.prompt_to_send when dispatch.send_to_target is true."
  ]
}