<a id="ops-operations"></a>

# Operações `ops`

<!-- i18n: source=docs/reference/operations/ops.md blob=490027bd1a70fa36f4eb50dd202cb2be08c4236f model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/ops.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/ops.md), which is authoritative.


Os campos exatos que cada operação `ops.*` recebe e retorna.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Toda op é um `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue; em uma chamada HTTP sem token em um servidor de usuário único, usa-se a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a do seu plano), e em [algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) também o namespace e o agente; veja [identidades e namespaces](/pt-BR/concepts/identities-and-namespaces). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica papel, tipo e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

<!-- prettier-ignore-start -->

<a id="opscapabilities"></a>

## `ops.capabilities`

A identidade é opcional: um cliente descobre a superfície com o token que tiver (apenas verificação de papel; nenhum namespace é endereçado).

`POST /v1/ops.capabilities` · MCP `loom_ops_capabilities` · papel `viewer` · leitura

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | `''` | O tenant (primeiro elemento da tupla de identidade). |
| `consumer` | `str` | `''` | A tag da integração que faz a chamada, registrada na linha do ledger. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `build_commit` | `str` | O commit do git a partir do qual a imagem em execução foi construída; vazio em uma execução a partir do código-fonte. |
| `schema_version` | `str` | A versão do schema de transmissão, como o cabeçalho `X-Schema-Version` a nomeia. |
| `ops` | `list[OpCapability]` | Toda operação registrada, ordenada por nome, incluindo as ocultas. |
| `consumer_field` | `str` | Todo campo de todo modelo de requisição que nomeia o consumer — a tag armazenada em cada linha do ledger. |

<a id="opshealth"></a>

## `ops.health`

Executa as autoverificações da implantação (contratos de schema, stubs de embedding, partes do ClickHouse, mix de ops, plano de procedimentos, workers) e informa cada uma como ok, warn ou fail.

`POST /v1/ops.health` · MCP `loom_ops_health` · papel `org_admin` · idempotente · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str \| None` | `None` | O namespace que a op lê ou grava. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `checks` | `list[OpsHealthCheck]` | Uma entrada por verificação de saúde (contratos de schema, stubs de embedding, partes, mix de ops, workers, ...), cada uma com seu status e, quando não for `ok`, um reparo sugerido. |
| `worker_status` | `dict[str, dict[str, Any]]` | Por worker em segundo plano neste processo: hora da última execução, duração, resultado, o tipo do último erro (`last_error_kind`), falhas consecutivas e total de execuções; vazio antes de qualquer worker ter executado. |
| `overall` | `Literal['ok', 'warn', 'fail']` | `fail` quando alguma verificação falhou; senão `warn` quando alguma emitiu aviso; senão `ok`. |

<a id="opsprojection_failureslist"></a>

## `ops.projection_failures.list`

Lista as falhas de projeção registradas: linhas derivadas (embeddings, arestas de grafo, resumos) que uma gravação não conseguiu produzir.

`POST /v1/ops.projection_failures.list` · MCP `loom_ops_projection_failures_list` · papel `org_admin` · idempotente · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str \| None` | `None` | O namespace que a op lê ou grava. |
| `projection` | `str` | `''` | Somente falhas desta projeção (a tabela derivada, como `memory_chunks` ou `entity_edges`); vazio lista todas as projeções. |
| `status` | `Literal['active', 'resolved', 'abandoned', '']` | `'active'` | `active` lista as falhas abertas, `resolved` as reparadas, `abandoned` aquelas das quais o reparo desistiu (o motivo está em `error_message`), vazio todas. |
| `limit` | `int` | `100` | No máximo esta quantidade de falhas, das mais recentes para as mais antigas. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `rows` | `list[ProjectionFailureRow]` | As falhas registradas que correspondem aos filtros, das mais recentes para as mais antigas. |
| `total` | `int` | Número de linhas retornadas (não a contagem além de `limit`). |

<a id="opsprojection_failuresresolve"></a>

## `ops.projection_failures.resolve`

Marca falhas de projeção como resolvidas por id, sem tentar novamente.

`POST /v1/ops.projection_failures.resolve` · MCP `loom_ops_projection_failures_resolve` · papel `org_admin` · idempotente · auditada · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `failure_ids` | `list[str]` | obrigatório | As falhas a marcar como resolvidas sem tentar novamente, de 1 a 500 ids. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `resolved` | `int` | Ids não vazios enviados para resolução; ids que não correspondem a nenhuma falha ativa são contados. |

<a id="opsprojection_failuresretry"></a>

## `ops.projection_failures.retry`

Tenta novamente as falhas de projeção abertas de um namespace, opcionalmente de um só tipo de projeção.

`POST /v1/ops.projection_failures.retry` · MCP `loom_ops_projection_failures_retry` · papel `org_admin` · idempotente · auditada · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str \| None` | `None` | O namespace que a op lê ou grava. |
| `projection` | `str` | `''` | Tenta novamente apenas as falhas desta projeção; vazio tenta novamente todas as projeções. |
| `limit` | `int` | `50` | No máximo esta quantidade de falhas ativas é reprocessada, das mais recentes para as mais antigas. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `results` | `list[ProjectionFailureRetryRow]` | Uma entrada por falha tentada, indicando se foi reprocessada e resolvida e, caso contrário, por quê. |
| `retried` | `int` | Falhas cuja projeção tem um caminho de nova tentativa e foi tentada. |
| `resolved` | `int` | Falhas cuja nova tentativa teve sucesso e que agora estão marcadas como resolvidas. |
| `abandoned` | `int` | Falhas das quais a nova tentativa desistiu, agora marcadas como abandonadas. |

<!-- prettier-ignore-end -->
