{
  "openapi": "3.1.0",
  "info": {
    "title": "Stoppage Execution Gate",
    "version": "2.0.0",
    "description": "Public synthetic integration contract for autonomous agents that must pass Stoppage enforcement before a simulated venue callback can run. Permit V2 is Ed25519-signed and offline-verifiable; Permit V1 remains available for compatibility but is never accepted by the enforcement SDK."
  },
  "servers": [
    {
      "url": "https://stoppage-txline.vercel.app",
      "description": "Public synthetic Judge Integration Lab"
    }
  ],
  "paths": {
    "/api/agent-gate": {
      "post": {
        "summary": "Evaluate an external agent action",
        "description": "Rebuilds a deterministic public World Cup checkpoint and evaluates the exact quote action. Version 2 returns an Ed25519-signed permit only for an ALLOW decision. Optional challenge fields expose compatibility diagnostics from the server verifier; the browser Bench Lite instead mutates the permit and runs all six attacks through @stoppage/sdk locally. The endpoint is synthetic and contains no private live match data.",
        "operationId": "evaluateAgentAction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/HandshakeRequestV1" },
                  { "$ref": "#/components/schemas/HandshakeRequestV2" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gate decision, optional permit, and optional adversarial result",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/HandshakeResponseV1" },
                    { "$ref": "#/components/schemas/HandshakeResponseV2" }
                  ]
                }
              }
            }
          },
          "400": { "description": "Invalid strict request body" },
          "405": { "description": "Only POST is supported" },
          "500": { "description": "Gate failed closed" }
        }
      }
    },
    "/api/agent-context": {
      "get": {
        "summary": "Discover the public synthetic integration context",
        "description": "Returns the complete deterministic Judge Lab checkpoint required to construct a Permit V2 request. It contains no private fixture identifier, feed record, or licensed payload.",
        "operationId": "discoverAgentContext",
        "responses": {
          "200": {
            "description": "Public synthetic action context",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicAgentContext" }
              }
            }
          },
          "405": { "description": "Only GET is supported" }
        }
      }
    },
    "/api/permit-keys": {
      "get": {
        "summary": "Discover Permit V2 verification keys",
        "description": "Returns the current active Ed25519 public verification key. The schema reserves RETIRED for a future rotation-retention configuration, which is not enabled in this deployment. Private signing material is never returned.",
        "operationId": "discoverPermitKeys",
        "responses": {
          "200": {
            "description": "Stoppage public verification key set",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerificationKeySet" }
              }
            }
          },
          "405": { "description": "Only GET is supported" },
          "503": { "description": "Verification keys unavailable" }
        }
      }
    },
    "/api/live-decision-tape": {
      "get": {
        "summary": "Inspect the approved Live Decision Tape",
        "description": "Returns a human-approved frozen aggregate derived from builder-operated TxLINE World Cup capture. It includes one sanitized signed Certified Reopen Permit V2 sample and public verification key. Replay permit time is enforcement execution time, never feed time; no fixture IDs, quote vectors, feed records, source timestamps, credentials, or hosted-worker uptime claim are exposed.",
        "operationId": "getLiveDecisionTape",
        "responses": {
          "200": {
            "description": "Approved recorded agent-enforcement evidence",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LiveDecisionTape"
                }
              }
            }
          },
          "404": {
            "description": "No human-approved tape has been published"
          },
          "405": { "description": "Only GET is supported" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Hash": {
        "type": "string",
        "pattern": "^0x[0-9a-f]{64}$"
      },
      "AgentId": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9-]{2,63}$"
      },
      "Audience": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._/-]{2,127}$"
      },
      "Nonce": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9:._-]{7,127}$"
      },
      "PublicAgentContext": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "dataMode",
          "scenario",
          "sequence",
          "subjectHash",
          "market",
          "quoteHash"
        ],
        "properties": {
          "version": { "const": 2 },
          "dataMode": { "const": "SYNTHETIC" },
          "scenario": { "type": "string" },
          "sequence": { "type": "integer", "minimum": 1 },
          "subjectHash": { "$ref": "#/components/schemas/Hash" },
          "market": { "const": "1X2" },
          "quoteHash": { "$ref": "#/components/schemas/Hash" }
        }
      },
      "HandshakeRequestV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "agentId",
          "command",
          "sequence",
          "subjectHash",
          "market",
          "quoteHash"
        ],
        "properties": {
          "version": { "const": 1 },
          "agentId": { "$ref": "#/components/schemas/AgentId" },
          "command": { "const": "PUBLISH_QUOTE" },
          "sequence": { "type": "integer", "minimum": 1, "maximum": 12 },
          "subjectHash": { "$ref": "#/components/schemas/Hash" },
          "market": { "const": "1X2" },
          "quoteHash": { "$ref": "#/components/schemas/Hash" },
          "challenge": {
            "type": "string",
            "enum": ["QUOTE_TAMPER", "RECEIPT_TAMPER", "EXPIRED_REPLAY"]
          }
        }
      },
      "HandshakeRequestV2": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "agentId",
          "audience",
          "nonce",
          "command",
          "sequence",
          "subjectHash",
          "market",
          "quoteHash"
        ],
        "properties": {
          "version": { "const": 2 },
          "agentId": { "$ref": "#/components/schemas/AgentId" },
          "audience": { "$ref": "#/components/schemas/Audience" },
          "nonce": { "$ref": "#/components/schemas/Nonce" },
          "command": { "const": "PUBLISH_QUOTE" },
          "sequence": { "type": "integer", "minimum": 1, "maximum": 12 },
          "subjectHash": { "$ref": "#/components/schemas/Hash" },
          "market": { "const": "1X2" },
          "quoteHash": { "$ref": "#/components/schemas/Hash" },
          "challenge": {
            "type": "string",
            "enum": [
              "QUOTE_TAMPER",
              "RECEIPT_TAMPER",
              "EXPIRED_REPLAY",
              "WRONG_AUDIENCE",
              "UNKNOWN_SIGNING_KEY",
              "REUSED_NONCE"
            ]
          }
        }
      },
      "GateResponseRequestV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "command",
          "sequence",
          "subjectHash",
          "market",
          "quoteHash"
        ],
        "properties": {
          "version": { "const": 1 },
          "command": { "const": "PUBLISH_QUOTE" },
          "sequence": { "type": "integer", "minimum": 1, "maximum": 12 },
          "subjectHash": { "$ref": "#/components/schemas/Hash" },
          "market": { "const": "1X2" },
          "quoteHash": { "$ref": "#/components/schemas/Hash" }
        }
      },
      "PermitV1": {
        "type": "object",
        "required": ["body", "hash"],
        "properties": {
          "body": {
            "type": "object",
            "properties": { "version": { "const": 1 } }
          },
          "hash": { "$ref": "#/components/schemas/Hash" }
        }
      },
      "PermitV2": {
        "type": "object",
        "additionalProperties": false,
        "required": ["alg", "body", "hash", "signature"],
        "properties": {
          "alg": { "const": "Ed25519" },
          "body": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "version",
              "issuer",
              "kid",
              "agentId",
              "audience",
              "nonce",
              "command",
              "decision",
              "reason",
              "subjectHash",
              "market",
              "quoteHash",
              "configHash",
              "stateReceiptHash",
              "reopenProofHash",
              "sequence",
              "issuedAt",
              "expiresAt"
            ],
            "properties": {
              "version": { "const": 2 },
              "issuer": { "const": "stoppage" },
              "kid": { "type": "string" },
              "agentId": { "$ref": "#/components/schemas/AgentId" },
              "audience": { "$ref": "#/components/schemas/Audience" },
              "nonce": { "$ref": "#/components/schemas/Nonce" },
              "command": { "const": "PUBLISH_QUOTE" },
              "decision": {
                "type": "string",
                "enum": ["ALLOW_HEALTHY_QUOTE", "ALLOW_CERTIFIED_REOPEN"]
              },
              "reason": { "type": "string" },
              "subjectHash": { "$ref": "#/components/schemas/Hash" },
              "market": { "const": "1X2" },
              "quoteHash": { "$ref": "#/components/schemas/Hash" },
              "configHash": { "$ref": "#/components/schemas/Hash" },
              "stateReceiptHash": {
                "oneOf": [
                  { "$ref": "#/components/schemas/Hash" },
                  { "type": "null" }
                ]
              },
              "reopenProofHash": {
                "oneOf": [
                  { "$ref": "#/components/schemas/Hash" },
                  { "type": "null" }
                ]
              },
              "sequence": { "type": "integer", "minimum": 1 },
              "issuedAt": { "type": "integer" },
              "expiresAt": { "type": "integer" }
            }
          },
          "hash": { "$ref": "#/components/schemas/Hash" },
          "signature": {
            "type": "string",
            "description": "Base64url Ed25519 signature"
          }
        }
      },
      "GateDecision": {
        "type": "string",
        "enum": [
          "BLOCK_UNRESOLVED_INCIDENT",
          "BLOCK_INVALIDATED_BRANCH",
          "BLOCK_STREAM_UNHEALTHY",
          "BLOCK_QUOTE_STALE",
          "BLOCK_PERMIT_EXPIRED",
          "ALLOW_HEALTHY_QUOTE",
          "ALLOW_CERTIFIED_REOPEN"
        ]
      },
      "GateResultV1": {
        "type": "object",
        "properties": {
          "version": { "const": 1 },
          "command": { "const": "PUBLISH_QUOTE" },
          "decision": { "$ref": "#/components/schemas/GateDecision" },
          "reason": { "type": "string" },
          "evaluatedAt": { "type": "integer" },
          "sequence": { "type": "integer" },
          "permit": {
            "oneOf": [
              { "$ref": "#/components/schemas/PermitV1" },
              { "type": "null" }
            ]
          }
        }
      },
      "GateResultV2": {
        "type": "object",
        "properties": {
          "version": { "const": 2 },
          "command": { "const": "PUBLISH_QUOTE" },
          "decision": { "$ref": "#/components/schemas/GateDecision" },
          "reason": { "type": "string" },
          "evaluatedAt": { "type": "integer" },
          "sequence": { "type": "integer" },
          "permit": {
            "oneOf": [
              { "$ref": "#/components/schemas/PermitV2" },
              { "type": "null" }
            ]
          }
        }
      },
      "ChallengeResult": {
        "type": "object",
        "properties": {
          "challenge": { "type": "string" },
          "expected": { "const": "REJECT" },
          "valid": { "type": "boolean" },
          "decision": { "type": "string" },
          "reason": { "type": "string" }
        }
      },
      "HandshakeResponseV1": {
        "type": "object",
        "properties": {
          "version": { "const": 1 },
          "dataMode": { "const": "SYNTHETIC" },
          "request": {
            "$ref": "#/components/schemas/GateResponseRequestV1"
          },
          "result": { "$ref": "#/components/schemas/GateResultV1" },
          "challenge": {
            "oneOf": [
              { "$ref": "#/components/schemas/ChallengeResult" },
              { "type": "null" }
            ]
          }
        }
      },
      "HandshakeResponseV2": {
        "type": "object",
        "properties": {
          "version": { "const": 2 },
          "dataMode": { "const": "SYNTHETIC" },
          "request": { "$ref": "#/components/schemas/HandshakeRequestV2" },
          "result": { "$ref": "#/components/schemas/GateResultV2" },
          "challenge": {
            "oneOf": [
              { "$ref": "#/components/schemas/ChallengeResult" },
              { "type": "null" }
            ]
          }
        }
      },
      "LiveDecisionTape": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "status",
          "evidenceType",
          "network",
          "source",
          "operation",
          "hostingClaim",
          "dataBoundary",
          "timingDisclosure",
          "captureModes",
          "contract",
          "signer",
          "counters",
          "decisions",
          "sampleProof",
          "candidateHash",
          "approvedAt",
          "approval"
        ],
        "properties": {
          "version": { "const": 1 },
          "status": { "const": "AVAILABLE" },
          "evidenceType": {
            "const": "RECORDED_BUILDER_ATTESTED_TXLINE_DECISION_TAPE"
          },
          "network": { "const": "solana-mainnet" },
          "source": {
            "const": "TXLINE_CAPTURE_PROVENANCE_NOT_INDEPENDENTLY_VERIFIED"
          },
          "operation": { "const": "BUILDER_OPERATED_CAPTURE" },
          "hostingClaim": { "const": "RECORDED_CAPTURE_NOT_HOSTED_UPTIME" },
          "dataBoundary": { "type": "string" },
          "timingDisclosure": {
            "const": "PERMIT_ISSUED_AT_IS_ENFORCEMENT_EXECUTION_TIME_NOT_FEED_TIME"
          },
          "captureModes": {
            "type": "object",
            "additionalProperties": false,
            "required": ["live", "privateCaptureReplay"],
            "properties": {
              "live": { "type": "integer", "minimum": 0 },
              "privateCaptureReplay": { "type": "integer", "minimum": 0 }
            }
          },
          "contract": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "command",
              "enforcement",
              "intendedAgent",
              "adversaryAgent"
            ],
            "properties": {
              "command": { "const": "PUBLISH_QUOTE" },
              "enforcement": {
                "const": "CALLBACK_AFTER_OFFLINE_ED25519_VERIFICATION_ONLY"
              },
              "intendedAgent": { "$ref": "#/components/schemas/AgentId" },
              "adversaryAgent": { "$ref": "#/components/schemas/AgentId" }
            }
          },
          "signer": {
            "type": "object",
            "additionalProperties": false,
            "required": ["issuer", "kid", "alg", "publicKey"],
            "properties": {
              "issuer": { "const": "stoppage" },
              "kid": { "type": "string" },
              "alg": { "const": "Ed25519" },
              "publicKey": { "type": "string" }
            }
          },
          "counters": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "capturedRequests",
              "blockedRequests",
              "verifiedPermits",
              "callbacksAfterBlock",
              "callbacksWithoutVerifiedPermit",
              "crossAgentPermitTheftsRejected"
            ],
            "properties": {
              "capturedRequests": { "type": "integer", "minimum": 1 },
              "blockedRequests": { "type": "integer", "minimum": 1 },
              "verifiedPermits": { "type": "integer", "minimum": 1 },
              "callbacksAfterBlock": { "const": 0 },
              "callbacksWithoutVerifiedPermit": { "const": 0 },
              "crossAgentPermitTheftsRejected": {
                "type": "integer",
                "minimum": 1
              }
            }
          },
          "decisions": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "allowHealthyQuote",
              "allowCertifiedReopen",
              "blockedUncertainty",
              "blockedOther"
            ],
            "properties": {
              "allowHealthyQuote": { "type": "integer", "minimum": 0 },
              "allowCertifiedReopen": { "type": "integer", "minimum": 1 },
              "blockedUncertainty": { "type": "integer", "minimum": 0 },
              "blockedOther": { "type": "integer", "minimum": 0 }
            }
          },
          "sampleProof": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "decision",
              "permit",
              "intendedAgent",
              "crossAgentAttempt"
            ],
            "properties": {
              "decision": {
                "type": "string",
                "const": "ALLOW_CERTIFIED_REOPEN"
              },
              "permit": { "$ref": "#/components/schemas/PermitV2" },
              "intendedAgent": {
                "$ref": "#/components/schemas/TapeAgentOutcome"
              },
              "crossAgentAttempt": {
                "$ref": "#/components/schemas/TapeAgentOutcome"
              }
            }
          },
          "candidateHash": { "$ref": "#/components/schemas/Hash" },
          "approvedAt": { "type": "string", "format": "date-time" },
          "approval": {
            "type": "object",
            "additionalProperties": false,
            "required": ["statement"],
            "properties": { "statement": { "type": "string" } }
          }
        }
      },
      "TapeAgentOutcome": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "audience",
          "verification",
          "callbackInvoked",
          "callbackInvokedAt",
          "callbackReceiptHash"
        ],
        "properties": {
          "id": { "$ref": "#/components/schemas/AgentId" },
          "audience": { "$ref": "#/components/schemas/Audience" },
          "verification": { "type": "string" },
          "callbackInvoked": { "type": "boolean" },
          "callbackInvokedAt": {
            "oneOf": [
              { "type": "string", "format": "date-time" },
              { "type": "null" }
            ]
          },
          "callbackReceiptHash": {
            "oneOf": [
              { "$ref": "#/components/schemas/Hash" },
              { "type": "null" }
            ]
          }
        }
      },
      "VerificationKeySet": {
        "type": "object",
        "additionalProperties": false,
        "required": ["version", "issuer", "keys"],
        "properties": {
          "version": { "const": 1 },
          "issuer": { "const": "stoppage" },
          "keys": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["kid", "alg", "use", "publicKey", "status"],
              "properties": {
                "kid": { "type": "string" },
                "alg": { "const": "Ed25519" },
                "use": { "const": "sig" },
                "publicKey": { "type": "string" },
                "status": { "type": "string", "enum": ["ACTIVE", "RETIRED"] }
              }
            }
          }
        }
      }
    }
  }
}