Configurar rodadas

Esta página mostra como mudar as fontes e os arquivos de entrada de uma rodada pela API: opções da rodada, configuração da rodada, entradas NEWAVE e DECOMP, arquivos de entrada e prévia de EARM. O significado de cada escolha (o que é VAZPAST, cortes, DADGNL, EARM base) está em Configuração da rodada, que descreve as mesmas opções na tela do Portal. Os campos completos estão na referência interativa.

Há duas rotas de alteração:

Rota	Controle de concorrência	Quando usar
PATCH .../options	base_deck_version (versão do estudo)	Trocar fontes, entradas e executáveis de uma rodada num único pedido. Responde 202 Operation.
/configuration	número de revisão da configuração da rodada	Salvar, conferir e aplicar em etapas a sequência de regras, a política de ajustes condicionais e as entradas, inclusive em rodadas que já executaram.

Opções da rodada

PATCH /studies/{study_key}/rodadas/{round_key}/options recebe base_deck_version e options, com Idempotency-Key:

curl -sS -X PATCH "$MYRIA_API/api/v1/studies/$STUDY_KEY/rodadas/$ROUND_KEY/options" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opcoes-206-001" \
  -d '{
    "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
    "options": {
      "prevs_source": null,
      "gevazp": {"binario_id": 12, "run_gevazp": true}
    }
  }'

GET /studies/{study_key}/rodadas/{round_key}/options (escopo studies:read) devolve as opções em vigor, o base_deck_version atual do estudo e, em options.earm_control, o etag que o PATCH precisa repetir em expected_etag. Os executáveis aceitos em binario_id e gevazp.binario_id vêm de GET /binaries (escopo studies:read), que lista id, model, name e default (padrão da organização); use ?model=decomp para filtrar.

Acompanhe a Operation até succeeded antes de executar a rodada. Ao concluir, a lista de arquivos de entrada e a verificação dos pré-requisitos refletem a nova versão do estudo, inclusive quando a alteração muda apenas o limite de tentativas do DESSEM.

options precisa ter ao menos um campo e recusa campos desconhecidos. Os campos aceitos são:

Campo	Rodada	Uso
prevs_source	DECOMP	null usa o PREVS do próprio deck. Um objeto {source:"external", org, repo, path, file, ref} usa um arquivo do Git, com ref sendo o commit completo.
gevazp	DECOMP	binario_id (versão do GEVAZP), run_gevazp e, opcionalmente, deck_base com a base GEVAZP fixada em commit.
binario_id	todas	Versão do executável da rodada, um id de GET /binaries. Precisa ser do mesmo modelo e da sua organização.
decomp_base	DECOMP	Rodada do estudo usada como base: {"source":"chain","round_key":"..."}.
deck_base	NEWAVE gerado	Troca a base estrutural por uma rodada NEWAVE anterior do mesmo estudo: {"source":"chain","round_key":"..."}.
newave	DECOMP RV0 gerada	NEWAVE de formação: {"source":"chain","round_key":"..."} ou uma pasta do Git {source:"external", org, repo, path, ref}.
earm_control	NEWAVE, DECOMP	Ajuste de EARM. Veja Prévia de EARM.
newave_hydrology, newave_adterm, newave_earm	NEWAVE	Entradas NEWAVE.
decomp_cuts, decomp_hydrology, gevazp_history, decomp_dadgnl, decomp_earm	DECOMP	Entradas DECOMP.
dessem_hydrology	DESSEM	DADVAZ da rodada.
dessem_fcf	DESSEM	FCF do DESSEM.
decomp_max_inviab_attempts, dessem_max_inviab_attempts	DECOMP, DESSEM	Tentativas de tratamento de inviabilidade, de 1 a 20 (padrão 5), contando a primeira execução. No DESSEM, se o deck não convergir depois da última tentativa, a rodada termina como não convergida e o dia seguinte da trilha continua sendo rolado a partir dela. Mudar só esse valor não altera os arquivos do deck.

Com run_gevazp: true, a rodada DECOMP executa o GEVAZP como parte da própria tentativa e usa o vazoes.* gerado. Com run_gevazp: false, o deck já precisa ter o vazoes.*; sem ele, a rodada fica bloqueada. Não há rodada GEVAZP isolada.

Um prevs_source externo precisa estar nas pastas de PREVS autorizadas para a organização (403 forbidden_prevs_source) e o arquivo precisa existir no commit informado (404 prevs_source_not_found).

Quando Prevs muda no DECOMP, os NEWAVEs seguintes que usam o Prevs dessa rodada recebem uma nova revisao de aquisicao dos insumos. A proxima execucao usa a escolha salva; revisoes e snapshots anteriores permanecem no historico. Repetir a mesma escolha nao cria outra revisao.

Trocar deck_base remonta a rodada NEWAVE e as rodadas geradas a partir dela. Se alguma delas já tiver tentativas ou resultados, envie "confirm_invalidate_results": true no corpo, ao lado de options; sem isso, o pedido é recusado. A confirmação limpa o estado atual das rodadas afetadas e preserva o histórico das tentativas. confirm_invalidate_results só é aceito junto com deck_base. Rodadas importadas não podem ser remontadas assim.

Ao substituir a base DECOMP encadeada, a rodada deixa de aguardar a base anterior. A selecao atual de cortes herdados e preservada como escolha manual, e a antecessora da trilha passa a refletir a nova base. A rodada anterior pode ser excluida se nenhum outro insumo ou rodada ainda a referenciar. Bases externas são escolhidas pelo seletor do Portal, não por este PATCH. Uma base de outro estudo deve apontar para o commit que contem os resultados necessarios; ela nao e reexecutada ao iniciar a rodada consumidora. Para uma rodada gerenciada, o caminho estudo_<numero>/rodada_<numero> e resolvido pelos resultados certificados exatamente nesse commit, nunca pelos resultados mais recentes.

Referências históricas da trilha, sozinhas, não impedem excluir uma rodada NEWAVE ou DECOMP: elas são reancoradas na ancestralidade da rodada excluída. Referências de insumos ainda usadas por outra rodada, inclusive em bifurcações, continuam impedindo a exclusão. Trocar uma base NEWAVE preserva as escolhas independentes de EARM e ADTERM. Se a rodada era agrupada como sensibilidade da base substituída, essa associação passa para a nova base; não permanece uma dependência da base antiga apenas pelo agrupamento.

O pedido é assíncrono: a versão do estudo só muda quando a Operation termina. Em succeeded, result traz study_key, round_key, a nova deck_version, changed_fields e rematerialized_round_keys. Se base_deck_version não for a versão atual, a resposta é 409. Outra alteração em andamento no mesmo estudo também retorna conflito.

Quando a alteração exige montar arquivos de novo, a Operation só termina depois que as rodadas de rematerialized_round_keys forem montadas e validadas. Enquanto isso, essas rodadas ficam com prontidão pendente e outra expansão no mesmo estudo é recusada. Após succeeded, use a deck_version devolvida em result no próximo pedido.

Entradas NEWAVE

Estes campos definem de onde vem cada arquivo de entrada. Todos usam schema_version: 1 e selection_policy: "manual". Uma fonte externa usa requested_source com origin: "external", kind, org, repo, path, file, ref (commit completo) e sha256 do arquivo.

Campo	Modos (requested_mode)
newave_hydrology (VAZPAST)	keep_base mantém o VAZPAST original; replace_vazpast usa um arquivo kind: "vazpast"; base_plus_prevs aplica um PREVS (kind: "prevs") ou o PREVS do DECOMP anterior (requested_source: {"origin": "sumario_base", "kind": "prevs"}). Informe target_period (AAAAMM).
newave_adterm (ADTERM)	previous_decomp_gnl usa RELGNL/BENGNL do DECOMP anterior (requested_source: {"origin": "sumario_base"}); roll_base rola a base; replace_adterm usa um arquivo kind: "adterm". Informe target_period.
newave_earm (EARM inicial)	decomp encadeia com o DECOMP anterior (requested_source: {"origin": "sumario_base"}); replace_confhd usa um CONFHD.DAT (kind: "confhd"). Não informe target_period.

Exemplo, substituindo o VAZPAST:

{
  "base_deck_version": "0123456789abcdef0123456789abcdef01234567",
  "options": {
    "newave_hydrology": {
      "schema_version": 1,
      "selection_policy": "manual",
      "requested_mode": "replace_vazpast",
      "target_period": "202609",
      "requested_source": {
        "origin": "external", "kind": "vazpast",
        "org": "minha-org", "repo": "decks_ons", "path": "newave/202609",
        "file": "VAZPAST.DAT",
        "ref": "0123456789abcdef0123456789abcdef01234567",
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    }
  }
}

A mesma chamada pode trocar VAZPAST e ADTERM juntos. A troca publica só os arquivos afetados e a configuração; os demais arquivos do deck não são remontados. Se uma das fontes não puder ser validada, nenhuma das duas é aplicada. Uma fonte ausente ou inválida nunca é substituída por outro modo automaticamente.

Entradas DECOMP

Campo	Modos (requested_mode)
decomp_cuts (cortes)	schema_version: 2. keep_base usa o par de cortes do próprio deck importado; linked_newave usa um NEWAVE do estudo (requested_source: {"origin":"internal","role":"linked_newave","round_key":"..."}) ou uma pasta NEWAVE do Git ({"origin":"external","role":"linked_newave","kind":"subtree", org, repo, path, "tracking_ref":"main"}).
decomp_hydrology (VAZOES)	keep_base, replace_vazoes (arquivo kind: "vazoes", nome vazoes.rvN) ou generate_prevs (gera o vazoes pelo GEVAZP a partir do PREVS). Informe target_period e target_rv.
gevazp_history (VAZOES.DAT de entrada do GEVAZP)	update_prevs (padrão) herda o histórico da trilha e incorpora os PREVS anteriores; replace_vazoes_dat usa um arquivo kind: "vazoes_dat".
decomp_dadgnl (DADGNL)	keep_base, roll_base, base_plus_relgnl (kind: "relgnl"), base_plus_bengnl (kind: "bengnl") ou replace_dadgnl (kind: "dadgnl"). cadence aceita monthly (padrão) ou weekly.
decomp_earm (EARM inicial)	previous_decomp_result encadeia com o resultado do DECOMP anterior; replace_uh usa um bloco UH (kind: "uh").

Com linked_newave, cada nova tentativa fixa o commit mais recente da referência e registra o commit usado. Os cortes só existem quando o NEWAVE de origem tem resultado válido; sem ele, a execução é recusada antes de começar.

Exemplo, substituindo o VAZOES:

{
  "decomp_hydrology": {
    "schema_version": 1,
    "selection_policy": "manual",
    "requested_mode": "replace_vazoes",
    "target_period": "202609",
    "target_rv": 0,
    "requested_source": {
      "origin": "external", "kind": "vazoes",
      "org": "minha-org", "repo": "decks_ons", "path": "decomp/202609",
      "file": "vazoes.rv0",
      "ref": "0123456789abcdef0123456789abcdef01234567",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

Códigos que você pode receber ao configurar ou executar hidrologia DECOMP: decomp_hydrology_prevs_required e decomp_hydrology_gevazp_base_required (falta PREVS ou base GEVAZP para generate_prevs), decomp_hydrology_stage_mismatch e decomp_hydrology_target_mismatch (o VAZOES não corresponde ao calendário do DADGER).

Uma EARM que ainda não pode ser calculada, por exemplo porque o DECOMP anterior não executou, deixa a rodada montada e editável, com uma pendência: a execução só é liberada quando a fonte estiver resolvida.

FCF do DESSEM

Em uma rodada DESSEM, dessem_fcf troca a FCF por um pacote externo completo, com source: "external". O Myria confere os arquivos no commit informado, seus hashes e a semana operativa, e troca só os arquivos da FCF. Rodadas seguintes já criadas mantêm a FCF que tinham. dessem_fcf e dessem_max_inviab_attempts só são aceitos em rodadas DESSEM.

DADVAZ do DESSEM

dessem_hydrology escolhe o DADVAZ da rodada. Use {"requested_mode":"rolled"} para restaurar o arquivo da rolagem do deck. Nos modos tok e file, envie requested_source com os campos origin: "external", kind: "dadvaz", org, repo, path, file, ref (commit completo) e sha256 (hash do conteúdo). O modo tok exige a captura em terceiros/tok/dadvaz/ da própria organização; uploads ficam no repositório arquivos, em dadvaz/<hash>/DADVAZ.DAT.

O arquivo deve existir no commit informado, ter até 2 MiB e iniciar às 00:00 na data operativa da rodada. O Myria confere os bytes, a data e o hash antes de publicar a alteração. Salve em configuration e aplique a revisão pelo fluxo abaixo, ou envie options.dessem_hydrology pelo endpoint de opções. Esse endpoint responde 202 Operation; aguarde succeeded para confirmar a publicação do DADVAZ escolhido. A aplicação substitui somente esse arquivo; preserva os demais arquivos editados do deck e as rodadas seguintes já criadas. O arquivo rolado permanece disponível para restauração. Novos D+ preferem TOK quando existe mapa compatível; essa escolha fica fixada entre a prévia e a confirmação.

Configuração da rodada

A configuração da rodada guarda, com um número de revisão, a sequência de regras (rule_stack), a política de ajustes condicionais (phase_policy) e as configurações de entrada (contracts). O fluxo tem três passos: salvar a configuração desejada, conferir o efeito e aplicar.

Consultar. GET /studies/{study_key}/rodadas/{round_key}/configuration devolve configuration_revision (o número de revisão atual), desired (a configuração salva), applied (a última aplicada), attempt (a última tentativa de execução), rule_stack e readiness. Uma rodada que nunca foi configurada responde com desired.state: "implicit" e revisão 0. Se a rodada só tem registro dos Cards usados na última execução, applied.source é execution_snapshot e applied.revision é null: a configuração completa ainda não foi aplicada. applied.rule_stack_revision identifica a revisão dos Cards, numerada de forma independente.

Salvar. PATCH na mesma rota, com Idempotency-Key. É síncrono e responde 200 com a configuração e a nova revision. Não altera arquivos:

{
  "schema_version": 1,
  "expected_configuration_revision": 3,
  "changes": {
    "phase_policy": {"source_declared_preflight": "apply"},
    "contracts": {
      "decomp_cuts": {
        "schema_version": 2,
        "selection_policy": "manual",
        "requested_mode": "linked_newave",
        "requested_source": {"origin": "internal", "role": "linked_newave", "round_key": "minha-org-205"}
      }
    }
  }
}

Campo	Uso
schema_version	Opcional; só 1.
expected_configuration_revision	Número de revisão que você leu. Pode ir no cabeçalho If-Match em vez do corpo. Divergência retorna 409 configuration_revision_conflict.
expected_input_commit	Opcional. Commit de entrada que você espera; se a rodada mudou, 409 configuration_input_commit_conflict.
changes.rule_stack	Sequência de regras da rodada: uma lista de itens como em Regras de deck, ou {"origin":"study_default"} para voltar ao padrão do estudo.
changes.phase_policy	{"source_declared_preflight": "apply" | "skip"}. skip ignora só a seção antes_de_rodar dos Cards; o antes_de_rodar da base, a montagem, a EARM e a hidrologia continuam.
changes.contracts	Configurações de entrada, com os mesmos campos da rota de opções. Esses campos também podem ir direto em changes. null remove a configuração.

Rodadas DESSEM não aceitam rule_stack nem phase_policy.

Conferir. POST .../configuration/preview recebe o mesmo corpo, sem Idempotency-Key e com o número de revisão opcional. Devolve a configuração resultante sem gravar nada e sem montar arquivos.

Aplicar. POST .../configuration/apply monta os arquivos da revisão salva. Exige Idempotency-Key e o número de revisão (no corpo ou em If-Match); aceita expected_input_commit e confirm_invalidate_results:

curl -sS -X POST \
  "$MYRIA_API/api/v1/studies/$STUDY_KEY/rodadas/$ROUND_KEY/configuration/apply" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: aplicar-206-r4" \
  -d '{"expected_configuration_revision": 4}'

A resposta é 202 Operation. applied só muda quando o pedido termina. Se a rodada já tiver resultado ou execução anterior, o pedido é recusado com 409 configuration_results_confirmation_required: repita com "confirm_invalidate_results": true depois de confirmar com quem usa esses resultados. A aplicação invalida só o resultado atual; tentativas e registros anteriores ficam no histórico.

Se a montagem falhar, a operação mantém error.code igual a round_configuration_apply_failed. Quando houver uma causa identificada, error.diagnostic_code informa o código, por exemplo inverted_limits para limites inferior e superior invertidos. Use o código para identificar a causa e corrigir o Card.

Em uma DECOMP RV0 gerada, aplicar um novo NEWAVE de formação (newave) remonta também as rodadas geradas seguintes. Aplicar só decomp_cuts muda os cortes preparados para a próxima execução, sem remontar o deck. Estudos compartilhados são somente leitura (409 configuration_shared_deck).

Arquivos de entrada

GET /studies/{study_key}/inputs lista as entradas do estudo (paginação por cursor), com input_id, round_key, name, selected, state, size_bytes, sha256 e deck_sha.

POST /studies/{study_key}/inputs envia um arquivo avulso ou um ZIP parcial, em multipart/form-data, até 128 MiB:

curl -sS -X POST "$MYRIA_API/api/v1/studies/$STUDY_KEY/inputs" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Idempotency-Key: prevs-206-001" \
  -F "base_deck_version=0123456789abcdef0123456789abcdef01234567" \
  -F "round_key=minha-org-206" \
  -F "file=@./prevs.rv0"

Para um arquivo avulso, informe a rodada em round_key. Num ZIP parcial, cada arquivo fica na pasta da sua rodada, rodada_<número>, dentro de estudo_<número>. O nome do arquivo é exato. Enviar um arquivo não o torna o arquivo selecionado da rodada: para usá-lo, ajuste as opções da rodada.

A resposta é 202 Operation. Erros comuns do pedido:

• source_integrity_mismatch: o arquivo armazenado mudou depois de aceito. Envie de novo;
• input_version_conflict: o mesmo arquivo foi alterado por outra pessoa desde base_deck_version. Consulte a versão atual e reenvie.

DELETE /studies/{study_key}/inputs/{input_id} não tem corpo e exige If-Match com a deck_version atual. O arquivo sai da versão atual, mas o registro continua na lista com state: "missing", para auditoria. Se o arquivo excluído era o selecionado da rodada, ela fica indisponível até ser corrigida.

Arquivos da rodada

GET /studies/{study_key}/rodadas/{round_key}/files lista os arquivos da pasta da rodada, com name, path, type, size e classification (input, output ou unknown). O filtro kind aceita input, output, unknown ou all (padrão). unknown indica que ainda não há evidência para classificar o arquivo. A rota aceita limit (até 100), mas não tem cursor: a resposta traz page.limit e page.has_more. Parâmetros kind ou limit inválidos retornam 400. Rodadas ocultas enquanto uma operação prepara sua publicação também retornam 404; seus arquivos só ficam acessíveis depois que a operação publica a rodada.

{
  "study_key": "minha-org-191",
  "round_key": "minha-org-206",
  "rodada": {"name": "DC 09/26 RV2"},
  "data": [{"name": "dadger.rv2", "classification": "input", "size": 481233}],
  "page": {"limit": 50, "has_more": false}
}

GET .../files/{filename} baixa um arquivo pelo nome, sem subpastas. A resposta contém os bytes reais do arquivo, inclusive quando ele está armazenado em Git LFS. Se o arquivo LFS não puder ser obtido, o download responde 500 internal_error e não entrega o ponteiro Git. Nas duas rotas, rodada fora do estudo responde 404 rodada_not_found e falha ao ler o repositório responde 500 internal_error. No download, nome com caminho responde 400 invalid_filename e arquivo inexistente, 404 file_not_found. Para resultados de execução, prefira os arquivos de resultado, que têm hash e histórico.

Tags da rodada

Tags são rótulos de gestão da organização. Não mudam o deck nem a versão do estudo, e agendamentos as usam para escolher o NEWAVE que fornece os cortes de um mês (veja Agendamentos).

GET /studies/{study_key}/rodadas/{round_key}/tags (studies:read) devolve as tags. PUT /studies/{study_key}/rodadas/{round_key}/tags (studies:write, com Idempotency-Key) substitui o conjunto inteiro; uma lista vazia remove todas e repetir o mesmo pedido não muda nada:

curl -sS -X PUT "$MYRIA_API/api/v1/studies/$STUDY_KEY/rodadas/$ROUND_KEY/tags" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tags-206-001" \
  -d '{"tags": ["#corte_oficial", "base.novembro"]}'

{"study_key": "minha-org-191", "round_key": "minha-org-206", "tags": ["base.novembro", "corte_oficial"]}

Cada tag é gravada sem #, em minúsculas, com letras sem acento, números, _, - ou ., até 64 caracteres, no máximo 20 por rodada. Tag fora desse formato responde 400 invalid_tag; sem Idempotency-Key, 400 missing_idempotency_key. As tags também aparecem em tags de cada rodada na topologia.

GET /rodadas?tag=corte_oficial (studies:read) lista as rodadas da organização com a tag, das mais recentes para as mais antigas, com study_key, round_key, name, type, period (PMO) e status. A rota usa cursor e limit como as demais listas.

Facetas e busca de PREVS e cortes

PREVS da TOK e cortes de NEWAVE executados pelo Myria têm facetas automáticas, que aparecem em facets de cada nó da topologia. As buscas usam a mesma linguagem de filtro dos agendamentos: termos chave:valor separados por espaço, com #tag como atalho de tag:tag.

GET /prevs?filtro=modelo:gefs pmo:202609 rv:2 (studies:read) lista os PREVS da TOK da organização que casam com o filtro, da captura mais recente para a mais antiga, com repo, path, file e facets. Chaves aceitas: modelo, captura (AAAA-MM-DD), pmo (AAAAMM), rv e origem. A busca usa o índice de capturas completas da TOK.

GET /cortes?filtro=#corte_oficial pmo:202611 (studies:read) lista os NEWAVE da organização com cortes certificados que casam com o filtro, do mais recente para o mais antigo, com study_key, round_key, name e facets. Chaves aceitas: pmo, estudo, rodada, executado, trilha e tag.

As duas rotas aceitam limit. Filtro com chave desconhecida ou valor fora do formato responde 400 invalid_filter, com a correção na mensagem.

Trocar o modelo do PREVS

POST /studies/{study_key}/prevs-model-switch/preview (studies:read) calcula, sem gravar nada, a troca do modelo do PREVS da TOK nas rodadas do escopo:

curl -sS -X POST "$MYRIA_API/api/v1/studies/$STUDY_KEY/prevs-model-switch/preview" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "ETA40", "scope": "from_round", "round_key": "minha-org-206"}'

scope é study (padrão), track (a trilha de round_key) ou from_round (de round_key em diante na trilha). Cada item de items tem round_key, name, type, field (prevs_source nas DECOMPs, newave_hydrology no VAZPAST dos NEWAVEs), from, to, has_results e status:

status	Significado
change	Troca para to; capture diz se é a mesma captura (same) ou a mais recente (latest).
unchanged	A rodada já usa o modelo.
no_equivalent	Não há PREVS do modelo para o PMO e a RV da rodada.
no_facets	O PREVS atual não é da TOK (por exemplo, enviado à mão).

Para aplicar, repita os mesmos campos com o plan_hash da prévia em POST /studies/{study_key}/prevs-model-switch (studies:write, com Idempotency-Key). A resposta 202 traz a Operation, que aplica as opções de cada rodada em sequência e guarda um recibo por rodada em result.receipts. Se o estudo ou os PREVS disponíveis mudaram desde a prévia, a resposta é 409 plan_changed; sem nada para trocar, 400 nothing_to_change. Se uma rodada falhar, a Operation termina em failed com round_switch_failed, e as rodadas anteriores continuam trocadas.

Prévia de EARM

POST /studies/{study_key}/rodadas/{round_key}/earm-preview calcula o efeito de um ajuste de EARM sem gravar nada (studies:read, sem Idempotency-Key). Só vale para rodadas NEWAVE e DECOMP.

curl -sS -X POST \
  "$MYRIA_API/api/v1/studies/$STUDY_KEY/rodadas/$ROUND_KEY/earm-preview" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "earm_control": {
      "schema_version": 1,
      "mode": "target_pct",
      "operations": [{"scope": "ree", "id": "1", "kind": "target_pct", "value": 60}]
    }
  }'

mode é target_pct (meta em % da EARM), delta_pp (soma pontos percentuais) ou multiplier (multiplica). Cada operação usa scope ree ou sist, o id do REE ou subsistema e kind igual a mode. São até 12 operações, sem repetir o mesmo alvo; target_pct vai de 0 a 100 e multiplier não pode ser negativo.

A resposta traz study_key, round_key, rodada (name, type, rv), source (kind e commit da fonte lida) e intent, com mode, resolved_targets (para cada alvo, reference_earm_pct, target_earm_pct, achieved_earm_pct, residual_pp e status), seed_coverage e fixed_coverage. Traz também artifact, com filename, size_bytes, sha256 e coverage do arquivo que seria gerado.

Se o serviço de cálculo de EARM não responder, a API devolve 502 earm_upstream_unavailable.

Para gravar o ajuste, envie earm_control nas opções da rodada, no formato {"value": {...ajuste...}, "expected_etag": "..."}. value: null remove o ajuste. expected_etag identifica o ajuste atual e impede sobrescrever uma alteração feita por outra pessoa: leia-o em options.earm_control.etag no GET .../options. Quando a rodada ainda não tem ajuste, o valor é "chain". O ajuste é aplicado sobre a EARM base na preparação da execução, sempre a partir da fonte original. Para o mesmo ajuste pelo Portal, veja Ajuste EARM.

Converter ONS para CCEE

As rotas abaixo usam o prefixo /api/v1, autenticação Bearer e os escopos studies:read para GET e studies:write para POST. model aceita newave ou decomp. Perfis privados e referências Git ficam restritos à organização da chave.

Método e rota	Uso
GET /ons-ccee/profiles/{model}	Lista as 100 versões privadas mais recentes.
GET /ons-ccee/profiles/{model}?official=1	Lê o YAML oficial e sua referência Git fixa.
GET /ons-ccee/profiles/{model}/{version_id}	Lê uma versão privada, YAML e proveniência.
GET /ons-ccee/profiles/{model}/{version_id}?check_git=1	Compara com o Git atual e devolve git_update, incluindo adopt_token.
POST /ons-ccee/profiles/{model}	Valida YAML ou salva uma versão privada.
GET /studies/{study_key}/rodadas/{round_key}/ons-ccee	Confere elegibilidade e informa a origem.
POST /studies/{study_key}/rodadas/{round_key}/ons-ccee	Gera a prévia ou confirma uma conversão.

Para apenas validar, envie {"validate_yaml":"..."}. Para salvar, envie Idempotency-Key no cabeçalho e name e exatamente uma origem: yaml (texto UTF-8, até 2 MiB), official: true, ou gitea: {"org":"minha-org","repo":"arquivos","path":"regras/meu-perfil.yaml"}. A resposta 201 inclui version_id, sha256, publication, source, author e created_at. previous referencia a versão anterior da mesma organização e modelo. Para adotar exatamente os bytes comparados, envie name, previous e o adopt_token recebido; a comparação expira em uma hora.

Na rota da rodada, {"profile_version":"<version_id>"} gera a prévia (200), com diffs, hashes de entrada/saída e preview_token. Depois, envie {"preview_token":"...","name":"Convertido com meu perfil"} com Idempotency-Key. A resposta 202 contém operation_id e status_url. Reutilize a mesma chave e corpo após perda de resposta. Uma chave com outro corpo é recusada com 409.

Consulte a Operation até o estado terminal. No sucesso, result.round_key identifica a nova rodada e result.conversion registra origem, perfil, motor, hashes, diferenças e destino. A execução é solicitada separadamente pela API de execuções, quando a rodada estiver pronta. A origem deve declarar um deck de org-myria/decks_ons; uma rodada já convertida não é reconvertida por este fluxo. Prévia expirada ou deck alterado responde 409: gere outra prévia. Estudo e rodada são identificados por study_key e round_key.