@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/DATA-DICTIONARY.md

@@ -0,0 +1,2227 @@
+# Dicionário de dados — dashboard SQLite
+
+> Atualização v54: o arquivo SQLite persistido contém exatamente as tabelas `zaip_aios_activities`, `zaip_dim_zaip_agent`, `zaip_dim_llm_model` e `zaip_dim_provider`. As dimensões são semeadas pelos catálogos canônicos para preservar opções sem atividade. Dados técnicos são linhas `technical_payload` da fato (`payload_type`/`payload_json`); todos os consumidores os leem por views persistidas `zaip_vw_*` ou aliases TEMP de compatibilidade. Não há tabelas persistidas de índice, cache, arquivo ou segmentos de uso.
+
+### `zaip_dim_zaip_agent`
+
+Dimensão física das opções do catálogo de agentes atual. A chave é `zaip_agent`; `catalog_id`, `persona`, `job`, `role` e `catalog_hash` preservam o enriquecimento de catálogo disponível na reconstrução, inclusive para opções sem atividade.
+
+### `zaip_dim_llm_model`
+
+Dimensão física das opções de `model` do catálogo de preços atual, inclusive quando nenhuma atividade usou a opção.
+
+### `zaip_dim_provider`
+
+Dimensão física das opções de `provider` do catálogo de preços atual, inclusive quando nenhuma atividade usou a opção.
+
+## Propósito, escopo e convenções
+
+Schema v54 do read model SQLite descartável do dashboard. A definição está em `packages/local-runtime/src/sqlite-read-model.ts`; o banco local, quando presente, fica em `.local/dashboard-sqlite/read-model.sqlite`. A carga usa somente uma allowlist de Runs V2, entidades Markdown, artefatos canônicos e configuração. Telemetria agregada, `.agents/records/lifecycle`, projeções e outros agregados derivados não são fontes.
+
+`zaip_aios_activities` é a única tabela fato financeira. `canonical_run_index`, `canonical_work_items`, `canonical_executions`, `canonical_changes`, `canonical_decisions`, `files`, `read_model_source_state` e `read_model_metadata` são views técnicas reconstruídas das linhas `technical_payload` da fato. Toda view persistida tem o prefixo `zaip_vw_`; o runtime mantém aliases temporários somente para compatibilidade interna. Os tipos são as afinidades retornadas por `PRAGMA table_info`. Em views, a nulabilidade não é determinável de modo confiável pelo PRAGMA. Em tabelas, somente `NOT NULL` é afirmado; a chave primária é indicada sem inferir regras adicionais.
+
+### Semântica oficial de duração
+
+Nos KPIs e nas views diária, mensal e anual, `total_duration`, `operations_total_duration` e `cost_monitor_total_duration` têm a mesma semântica: tempo de relógio coberto pelas atividades canônicas que possuem tokens e duração conhecida. O cálculo prioriza `source_started_at` e `source_finished_at`; na ausência deles, pode reconciliar o intervalo entre início e fim do Run somente se ele for positivo e não exceder duas horas. Em seguida, separa intervalos na meia-noite de `America/Sao_Paulo` e une sobreposições antes da soma. Assim, atividades paralelas não duplicam tempo e um dia nunca excede 24 horas. O valor está em milissegundos e deve ser dividido por `3.600.000` para exibição em horas.
+
+`total_root_run_duration` e `total_sub_run_duration` são diagnósticos brutos. Eles não devem ser somados nem usados nos big numbers, pois Runs paralelas e Sub-Runs contidas no pai causariam dupla contagem.
+
+## Resumo de objetos
+
+| Objeto | Tipo | Grão | Finalidade |
+|---|---|---|---|
+| `zaip_aios_activities` | Tabela fato incremental | Uma linha atual por Run canônico. | Única tabela de negócio; preserva hierarquia de Runs e agentes, persona, cargo, provedor, modelo e métricas. |
+| `canonical_run_index` | View técnica | Uma linha por Run canônico. | Preserva cardinalidade, dimensões, eventos e duração efetiva para métricas oficiais, inclusive quando os tokens são desconhecidos e o Run não entra na fato financeira. |
+| `canonical_work_items` | View técnica | Uma linha por Task, SPEC ou PRD canônico. | Preserva entidades sem Run associado para que as views contem todo o acervo canônico, sem consumir lifecycle ou agregados antigos. |
+| `canonical_executions` | View técnica | Uma linha por Execution canônica. | Preserva tipo, origem e datas diretamente de `execution.md`, inclusive sem telemetria. |
+| `canonical_changes` | View técnica | Uma linha por Change canônica. | Preserva os campos da aba Mudanças diretamente de `change.md`. |
+| `canonical_decisions` | View técnica | Uma linha por Decision canônica. | Preserva decisões válidas diretamente dos Markdown em `decisions/`. |
+| `changes` | View | Uma linha por Change vigente. | Changes derivadas dos snapshots de trabalho da fato. |
+| `conversations` | View | Uma linha por Conversation vigente. | Conversations derivadas da fato. |
+| `cost_monitor_group_daily_cache` | View | Uma linha por dia, tipo e valor de grupo. | Agregado dimensional calculado sob demanda a partir das invocações. |
+| `cost_monitor_group_daily` | View | Uma linha por dia, tipo e valor de grupo. | Alias público do agregado dimensional. |
+| `cost_monitor_overview` | View | Uma linha por period_kind e period_key. | Duração, tokens e custos do Monitor de Custos derivados de overview. |
+| `daily_aggregate_cache` | View | Uma linha por dia civil de São Paulo. | Agregado diário calculado sob demanda; o nome permanece por compatibilidade. |
+| `daily_aggregates` | View | Uma linha por dia civil de São Paulo. | Alias público do agregado diário. |
+| `decisions` | View | Uma linha por Decision vigente. | Decisions derivadas da fato. |
+| `dimensions` | View | Uma linha por par dimensão/valor. | Valores distintos de filtros derivados da fato. |
+| `executions` | View | Uma linha por Execution vigente. | Execuções derivadas dos snapshots. |
+| `files` | View técnica | Uma linha por caminho relativo. | Snapshot técnico dos arquivos canônicos lidos. |
+| `invocation_usage` | View técnica | Uma linha por segmento canônico de uso. | Base reconstruível para auditar e consolidar preço por invocação; a UI não expõe cada chamada como linha. |
+| `invocations` | View | Uma linha por invocação vigente. | Compatibilidade sobre a fato, incluindo agente, persona, cargo, provedor, modelo e métricas. |
+| `operations_overview` | View | Uma linha por period_kind e period_key. | Duração operacional derivada de overview. |
+| `overview` | View | Uma linha por period_kind e period_key. | Agregados diário, mensal e anual derivados de daily_aggregates. |
+| `overview_annual` | View | Uma linha por ano. | Recorte anual de overview. |
+| `overview_daily` | View | Uma linha por dia. | Recorte diário de overview. |
+| `overview_monthly` | View | Uma linha por mês. | Recorte mensal de overview. |
+| `prd_summary` | View | Uma linha por PRD. | PRDs LEFT JOIN invocations; zero invocações preserva métricas NULL. |
+| `prds` | View | Uma linha por PRD vigente. | PRDs derivadas dos snapshots de trabalho da fato única. |
+| `read_model_metadata` | View técnica | Uma linha por chave de metadado. | Metadados técnicos do read model, incluindo versão do schema e informações de atualização. |
+| `spec_summary` | View | Uma linha por SPEC. | SPECs LEFT JOIN invocations; zero invocações preserva métricas NULL. |
+| `specs` | View | Uma linha por SPEC vigente. | SPECs derivadas dos snapshots de trabalho da fato única. |
+| `task_summary` | View | Uma linha por Task. | Tasks LEFT JOIN invocations; zero invocações preserva métricas NULL. |
+| `tasks` | View | Uma linha por Task vigente. | Tasks derivadas dos snapshots de trabalho da fato única. |
+| `work_items` | View | Uma linha por entidade de trabalho vigente. | União de Tasks, SPECs e PRDs para Lista e Kanban. |
+| `cost_monitor_agent_invocations` | View | Uma linha por agent_invocation_id. | Alias público de vw_cost_agent_invocations; Detalhe de invocações com provedor e modelo consolidados; usa mixed quando há mais de um valor conhecido. |
+| `cost_monitor_annual` | View | Uma linha por ano. | Alias público de vw_cost_annual; Métricas anuais de duração, tokens e custos estimados, com início e fim do período. |
+| `cost_monitor_conversations` | View | Uma linha por conversation_id. | Alias público de vw_cost_conversations; Tokens, custos estimados e invocações agregados por Conversation. |
+| `cost_monitor_daily` | View | Uma linha por dia. | Alias público de vw_cost_daily; Métricas diárias de duração, tokens e custos estimados, com início e fim do período. |
+| `cost_monitor_executions` | View | Uma linha por execution_id. | Alias público de vw_cost_executions; Tokens, custos estimados e quantidade de invocações agregados por Execution. |
+| `cost_monitor_models` | View | Uma linha por modelo LLM. | Alias público de vw_cost_models; Tokens, custos estimados e invocações distintas agregados por modelo conhecido. |
+| `cost_monitor_monthly` | View | Uma linha por mês. | Alias público de vw_cost_monthly; Métricas mensais de duração, tokens e custos estimados, com início e fim do período. |
+| `cost_monitor_overview_view` | View | Uma linha por período. | Alias público de vw_cost_overview; Métricas do Monitor de Custos para todos os grãos temporais. |
+| `cost_monitor_prds` | View | Uma linha por prd_id. | Alias público de vw_cost_prds; Tokens, custos estimados e invocações agregados por PRD. |
+| `cost_monitor_providers` | View | Uma linha por provedor LLM. | Alias público de vw_cost_providers; Tokens, custos estimados e invocações distintas agregados por provedor conhecido. |
+| `cost_monitor_specs` | View | Uma linha por spec_id. | Alias público de vw_cost_specs; Tokens, custos estimados e invocações agregados por SPEC. |
+| `cost_monitor_tasks` | View | Uma linha por task_id. | Alias público de vw_cost_tasks; Tokens, custos estimados e invocações agregados por Task. |
+| `cost_monitor_zaip_agents` | View | Uma linha por agente ZAIP. | Alias público de vw_cost_zaip_agents; Tokens, custos estimados e invocações agregados por identidade de agente. |
+| `first_fold_overview` | View | Uma linha por dia. | Alias público de vw_first_fold_overview; Projeção compacta da visão geral usada nos big numbers da primeira dobra. |
+| `first_fold_overview_all_time` | View | Uma linha para todo o histórico. | KPIs globais, limites do período e contagens de entidades já agregados para a abertura em Todo o Período. |
+| `first_fold_task_status_all_time` | View | Uma linha por status de Task. | Distribuição global de Tasks por status sem transportar as entidades individuais. |
+| `first_fold_task_risk_all_time` | View | Uma linha por risco de Task. | Distribuição global de Tasks por risco sem transportar as entidades individuais. |
+| `first_fold_task_metrics_all_time` | View | Uma linha para todo o histórico. | Médias por Task e data da Task mais recente, derivadas do agregado global. |
+| `first_fold_top_tasks_all_time` | View | Até cinco linhas, uma por Task. | Top 5 global por duração oficial desduplicada, com uso e participação no total. |
+| `first_fold_spec_status_all_time` | View | Uma linha por estágio de SPEC. | Distribuição global das SPECs por estágio para troca instantânea do botão. |
+| `first_fold_spec_classification_all_time` | View | Uma linha por classificação de SPEC. | Distribuição global entre sem Tasks, com Tasks e com retrabalho. |
+| `first_fold_spec_metrics_all_time` | View | Uma linha para todas as SPECs. | Totais, médias e última criação de SPEC já agregados. |
+| `first_fold_top_specs_all_time` | View | Até cinco linhas, uma por SPEC. | Top 5 de SPECs por duração acumulada de Runs raiz em todas as fases. |
+| `first_fold_prd_status_all_time` | View | Uma linha por estágio de PRD. | Distribuição global dos PRDs por estágio para troca instantânea do botão. |
+| `first_fold_prd_classification_all_time` | View | Uma linha por classificação de PRD. | Distribuição global entre sem Tasks, com Tasks e com retrabalho. |
+| `first_fold_prd_metrics_all_time` | View | Uma linha para todos os PRDs. | Totais, médias e última criação de PRD já agregados. |
+| `first_fold_top_prds_all_time` | View | Até cinco linhas, uma por PRD. | Top 5 de PRDs por duração acumulada de Runs raiz em todas as fases. |
+| `first_fold_prd` | View | Uma linha por PRD. | Alias público de vw_first_fold_prd_summary; Resumo compacto de PRDs para a primeira dobra. |
+| `first_fold_spec` | View | Uma linha por SPEC. | Alias público de vw_first_fold_spec_summary; Resumo compacto de SPECs para a primeira dobra. |
+| `first_fold_task` | View | Uma linha por Task. | Alias público de vw_first_fold_task_summary; Resumo compacto de Tasks para a primeira dobra. |
+| `first_fold_task_risk` | View | Uma linha por dia e risco. | Alias público de vw_first_fold_task_risk; Série compacta para o gráfico de risco de Tasks na primeira dobra. |
+| `first_fold_task_status` | View | Uma linha por dia e status. | Alias público de vw_first_fold_task_status; Série compacta para o gráfico de status de Tasks na primeira dobra. |
+| `first_fold_top_tasks` | View | Uma linha por Task, ordenada por duração decrescente. | Alias público de vw_first_fold_top_tasks; Ranking de Tasks com duração, tokens e custos acumulados; o consumidor aplica o limite Top 5. |
+| `operations_agent_invocations` | View | Uma linha por agent_invocation_id. | Alias público de vw_operations_agent_invocations; Invocações de agentes enriquecidas com risco da Task para a área Operação. |
+| `operations_annual` | View | Uma linha por ano. | Resumo anual completo de criação, Runs, validações, evidências, duração, tokens e custo. |
+| `operations_changes` | View | Uma linha por Change. | Alias público de vw_operations_changes; Projeção de Changes para a aba Operação. |
+| `operations_conversations` | View | Uma linha por conversation_id. | Alias público de vw_operations_conversations; Conversations com estado, risco consolidado, intervalo, duração e quantidade de invocações. |
+| `operations_daily` | View | Uma linha por dia. | Resumo diário completo de criação, Runs, validações, evidências, duração, tokens e custo. |
+| `operations_decisions` | View | Uma linha por Decision. | Alias público de vw_operations_decisions; Projeção de Decisions para a aba Operação. |
+| `operations_executions` | View | Uma linha por execution_id. | Alias público de vw_operations_executions; Executions com estado, risco consolidado, intervalo, duração e quantidade de invocações. |
+| `operations_monthly` | View | Uma linha por mês. | Resumo mensal completo de criação, Runs, validações, evidências, duração, tokens e custo. |
+| `operations_work_kanban` | View | Uma linha por cartão de trabalho. | Alias público de vw_operations_work_kanban; Entidades mínimas necessárias para cartões da aba Trabalho Kanban. |
+| `operations_work_list` | View | Uma linha por entidade de trabalho. | Alias público de vw_operations_work_list; Lista unificada de Tasks, SPECs e PRDs para a aba Trabalho Lista. |
+| `prd_summary_daily` | View | Uma linha por dia. | Alias público de vw_prd_summary_daily; Contagem diária de PRDs. |
+| `spec_summary_daily` | View | Uma linha por dia. | Alias público de vw_spec_summary_daily; Contagem diária de SPECs. |
+| `task_risk_daily` | View | Uma linha por dia e risco. | Alias público de vw_task_risk_daily; Distribuição diária de Tasks por classificação de risco. |
+| `task_status_daily` | View | Uma linha por dia e status. | Alias público de vw_task_status_daily; Distribuição diária de Tasks por estado canônico. |
+| `task_summary_daily` | View | Uma linha por dia. | Alias público de vw_task_summary_daily; Contagem diária de Tasks. |
+| `cost_agent_invocations` | View | Uma linha por agent_invocation_id. | Detalhe de invocações com provedor e modelo consolidados; usa mixed quando há mais de um valor conhecido. |
+| `cost_annual` | View | Uma linha por ano. | Métricas anuais de duração, tokens e custos estimados, com início e fim do período. |
+| `cost_conversations` | View | Uma linha por conversation_id. | Tokens, custos estimados e invocações agregados por Conversation. |
+| `cost_daily` | View | Uma linha por dia. | Métricas diárias de duração, tokens e custos estimados, com início e fim do período. |
+| `cost_executions` | View | Uma linha por execution_id. | Tokens, custos estimados e quantidade de invocações agregados por Execution. |
+| `cost_group_daily` | View | Uma linha por dia, tipo de grupo e valor. | Projeção do agregado dimensional diário do Monitor de Custos. |
+| `cost_models` | View | Uma linha por modelo LLM. | Tokens, custos estimados e invocações distintas agregados por modelo conhecido. |
+| `cost_monthly` | View | Uma linha por mês. | Métricas mensais de duração, tokens e custos estimados, com início e fim do período. |
+| `cost_overview` | View | Uma linha por período. | Métricas do Monitor de Custos para todos os grãos temporais. |
+| `cost_prds` | View | Uma linha por prd_id. | Tokens, custos estimados e invocações agregados por PRD. |
+| `cost_providers` | View | Uma linha por provedor LLM. | Tokens, custos estimados e invocações distintas agregados por provedor conhecido. |
+| `cost_specs` | View | Uma linha por spec_id. | Tokens, custos estimados e invocações agregados por SPEC. |
+| `cost_tasks` | View | Uma linha por task_id. | Tokens, custos estimados e invocações agregados por Task. |
+| `cost_zaip_agents` | View | Uma linha por agente ZAIP. | Tokens, custos estimados e invocações agregados por identidade de agente. |
+| `entities` | View | Uma linha por Task, SPEC ou PRD. | União normalizada de entidades de trabalho para consultas comuns. |
+| `first_fold_overview` | View | Uma linha por dia. | Projeção compacta da visão geral usada nos big numbers da primeira dobra. |
+| `first_fold_prd_summary` | View | Uma linha por PRD. | Resumo compacto de PRDs para a primeira dobra. |
+| `first_fold_spec_summary` | View | Uma linha por SPEC. | Resumo compacto de SPECs para a primeira dobra. |
+| `first_fold_task_risk` | View | Uma linha por dia e risco. | Série compacta para o gráfico de risco de Tasks na primeira dobra. |
+| `first_fold_task_status` | View | Uma linha por dia e status. | Série compacta para o gráfico de status de Tasks na primeira dobra. |
+| `first_fold_task_summary` | View | Uma linha por Task. | Resumo compacto de Tasks para a primeira dobra. |
+| `first_fold_top_tasks` | View | Uma linha por Task, ordenada por duração decrescente. | Ranking de Tasks com duração, tokens e custos acumulados; o consumidor aplica o limite Top 5. |
+| `operations_agent_invocations` | View | Uma linha por agent_invocation_id. | Invocações de agentes enriquecidas com risco da Task para a área Operação. |
+| `operations_annual` | View | Uma linha por ano. | Resumo anual completo de criação, Runs, validações, evidências, duração, tokens e custo. |
+| `operations_changes` | View | Uma linha por Change. | Projeção de Changes para a aba Operação. |
+| `operations_conversations` | View | Uma linha por conversation_id. | Conversations com estado, risco consolidado, intervalo, duração e quantidade de invocações. |
+| `operations_daily` | View | Uma linha por dia. | Resumo diário completo de criação, Runs, validações, evidências, duração, tokens e custo. |
+| `operations_decisions` | View | Uma linha por Decision. | Projeção de Decisions para a aba Operação. |
+| `operations_executions` | View | Uma linha por execution_id. | Executions com estado, risco consolidado, intervalo, duração e quantidade de invocações. |
+| `operations_monthly` | View | Uma linha por mês. | Resumo mensal completo de criação, Runs, validações, evidências, duração, tokens e custo. |
+| `operations_work_kanban` | View | Uma linha por cartão de trabalho. | Entidades mínimas necessárias para cartões da aba Trabalho Kanban. |
+| `operations_work_list` | View | Uma linha por entidade de trabalho. | Lista unificada de Tasks, SPECs e PRDs para a aba Trabalho Lista. |
+| `overview` | View | Uma linha por período. | Projeção integral da tabela overview. |
+| `overview_annual` | View | Uma linha por ano. | Visão geral filtrada para period_kind year. |
+| `overview_daily` | View | Uma linha por dia. | Visão geral filtrada para period_kind day. |
+| `overview_monthly` | View | Uma linha por mês. | Visão geral filtrada para period_kind month. |
+| `prd_summary` | View | Uma linha por PRD. | Projeção integral do resumo calculado de PRDs. |
+| `prd_summary_daily` | View | Uma linha por dia. | Contagem diária de PRDs. |
+| `spec_summary` | View | Uma linha por SPEC. | Projeção integral do resumo calculado de SPECs. |
+| `spec_summary_daily` | View | Uma linha por dia. | Contagem diária de SPECs. |
+| `task_risk_daily` | View | Uma linha por dia e risco. | Distribuição diária de Tasks por classificação de risco. |
+| `task_status_daily` | View | Uma linha por dia e status. | Distribuição diária de Tasks por estado canônico. |
+| `task_summary` | View | Uma linha por Task. | Projeção integral do resumo calculado de Tasks. |
+| `task_summary_daily` | View | Uma linha por dia. | Contagem diária de Tasks. |
+
+### `zaip_aios_activities`
+
+Tabela física incremental e única fato de negócio. As linhas com `payload_type IS NULL` correspondem a Runs canônicos deduplicados por `run_id` que possuam `total_tokens` conhecido, inclusive zero; linhas com `payload_type` preenchido são payloads técnicos que alimentam as views. Runs cujo total seja desconhecido permanecem nos arquivos canônicos, mas são excluídos das métricas financeiras. `activity_source_kind = agent_run` quando existe identidade canônica de invocação e `unassisted_turn` quando o Run não possui essa identidade.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `activity_row_id` | `TEXT` | Não nulo | Chave imutável física, no formato `ACTV-...`. |
+| `activity_source_kind` | `TEXT` | Não nulo | `agent_run` ou `unassisted_turn`. |
+| `activity_key` | `TEXT` | Não nulo | Identidade lógica estável da atividade observada. |
+| `source_path` | `TEXT` | Não nulo | Caminho canônico de origem. |
+| `source_hash` | `TEXT` | Não nulo | Hash para idempotência e auditoria. |
+| `source_occurred_at` | `TEXT` | Sim | Instante informado pela origem. |
+| `recorded_at` | `TEXT` | Não nulo | Instante de gravação. |
+| `version_activity_id` | `TEXT` | Sim | Linha `ACTV-...` anterior substituída por esta versão. |
+| `source_last_event_id` | `TEXT` | Sim | Último `event_id` canônico incorporado ao Run. |
+| `source_last_sequence` | `INTEGER` | Sim | Maior sequência canônica incorporada ao Run. |
+| `work_item_kind` | `TEXT` | Sim | `task`, `spec` ou `prd`. |
+| `title` | `TEXT` | Sim | Título do trabalho. |
+| `work_item_status` | `TEXT` | Sim | Estado do snapshot de trabalho. |
+| `work_stage` | `TEXT` | Sim | Etapa operacional disponível. |
+| `risk` | `TEXT` | Sim | Risco registrado. |
+| `run_role` | `TEXT` | Não nulo | Papel estrutural `root` ou `subrun`, independente de haver agente. |
+| `root_run_id` | `TEXT` | Não nulo | ID do Run raiz da árvore canônica. |
+| `parent_run_id` | `TEXT` | Sim | Run pai; `NULL` para raiz. |
+| `agent_run_id` | `TEXT` | Sim | ID do Agent Run da linha; `NULL` em atividade sem agente. |
+| `root_agent_run_id` | `TEXT` | Sim | ID do Agent Run raiz da árvore. |
+| `parent_agent_run_id` | `TEXT` | Sim | ID do Agent Run que delegou o atual. |
+| `agent_run_role` | `TEXT` | Sim | `root`, `subagent` ou `NULL`. |
+| `agent_invocation_id` | `TEXT` | Sim | Alias técnico legado do `agent_run_id`. |
+| `root_agent_invocation_id` | `TEXT` | Sim | Alias técnico legado do `root_agent_run_id`. |
+| `parent_agent_invocation_id` | `TEXT` | Sim | Alias técnico legado do `parent_agent_run_id`. |
+| `invocation_kind` | `TEXT` | Sim | Alias de compatibilidade: `orchestrator` ou `delegated`. |
+| `delegation_depth` | `INTEGER` | Sim | Nível de delegação. |
+| `execution_id` | `TEXT` | Sim | Execução ZAIP vinculada. |
+| `task_id` | `TEXT` | Sim | Task vinculada. |
+| `spec_id` | `TEXT` | Sim | SPEC vinculada. |
+| `prd_id` | `TEXT` | Sim | PRD vinculada. |
+| `change_id` | `TEXT` | Sim | Change vinculada. |
+| `conversation_id` | `TEXT` | Sim | Conversa vinculada. |
+| `run_id` | `TEXT` | Sim | Run canônico vinculado. |
+| `occurred_at` | `TEXT` | Sim | Instante principal da atividade. |
+| `occurred_day_sp` | `TEXT` | Sim | Dia civil de São Paulo. |
+| `execution_kind` | `TEXT` | Sim | Tipo operacional da execução. |
+| `entrypoint` | `TEXT` | Sim | Porta de entrada canônica. |
+| `work_type` | `TEXT` | Sim | Tipo canônico de trabalho. |
+| `phase` | `TEXT` | Sim | Fase observada. |
+| `purpose` | `TEXT` | Sim | Propósito observado. |
+| `status` | `TEXT` | Sim | Estado da atividade. |
+| `activity_kind` | `TEXT` | Sim | `conversation`, `planning` ou `development`. |
+| `zaip_agent` | `TEXT` | Sim | Nome interno do agente ZAIP. |
+| `zaip_agent_persona` | `TEXT` | Sim | Nome humanizado copiado do catálogo na ingestão. |
+| `zaip_agent_job` | `TEXT` | Sim | Cargo da persona copiado do catálogo. |
+| `zaip_agent_role` | `TEXT` | Sim | Papel técnico do catálogo. |
+| `agent_catalog_id` | `TEXT` | Sim | ID do agente no catálogo. |
+| `agent_catalog_hash` | `TEXT` | Sim | Hash do catálogo usado historicamente. |
+| `provider` | `TEXT` | Sim | Provedor único ou `mixed`. Quando a origem não informa provedor, mas informa modelo, o runtime pode inferi-lo a partir de modelo e cliente; esta versão do schema não expõe proveniência separada para essa inferência. |
+| `model` | `TEXT` | Sim | Modelo único ou `mixed`. |
+| `service_tier` | `TEXT` | Sim | Camada de serviço única ou `mixed`. |
+| `reasoning_effort` | `TEXT` | Sim | Esforço de raciocínio único ou `mixed`. |
+| `source_duration_ms` | `REAL` | Sim | Duração factual observada/reconciliada; nunca recebe estimativa. |
+| `duration_ms` | `REAL` | Sim | Duração observada/reconciliada da atividade; as views de invocação usam a medida temporal atribuída quando ela existe. |
+| `duration_provenance` | `TEXT` | Sim | Proveniência da duração registrada pela atividade; as views de invocação reportam `observed` quando há medida temporal atribuída e `unavailable` quando ela não existe. |
+| `input_tokens` | `REAL` | Sim | Tokens de entrada conhecidos. |
+| `cached_input_tokens` | `REAL` | Sim | Tokens de cache conhecidos. |
+| `output_tokens` | `REAL` | Sim | Tokens de saída conhecidos. |
+| `reasoning_tokens` | `REAL` | Sim | Tokens de raciocínio conhecidos. |
+| `total_tokens` | `REAL` | Sim | Total conhecido de tokens. |
+| `token_source` | `TEXT` | Sim | Origem canônica dos tokens; `mixed` se houver mais de uma conhecida. |
+| `usage_event_count` | `INTEGER` | Sim | Quantidade de eventos `usage.recorded` efetivos consolidados. |
+| `llm_call_count` | `INTEGER` | Sim | Chamadas LLM contabilizadas. |
+| `cost_usd` | `REAL` | Sim | Estimativa histórica em USD. |
+| `cost_brl` | `REAL` | Sim | Estimativa histórica em BRL. |
+| `cost_method` | `TEXT` | Sim | Método de cálculo do custo. |
+| `pricing_model` | `TEXT` | Sim | Modelo de precificação. |
+| `pricing_source` | `TEXT` | Sim | Fonte da precificação. |
+| `fx_rate` | `REAL` | Sim | Câmbio aplicado. |
+| `source_event_count` | `INTEGER` | Sim | Eventos canônicos consolidados. |
+| `root_run_duration` | `REAL` | Sim | Duração conhecida do Agent Run raiz; `NULL` nas demais linhas. |
+| `sub_run_duration` | `REAL` | Sim | Duração conhecida do subagente; `NULL` nas demais linhas. |
+
+## Observações de uso
+
+### Modelo físico e aliases v54
+
+| Grupo | Fonte no SQLite | Regra de leitura |
+|---|---|---|
+| Fato de atividade | `zaip_aios_activities` | Fonte de negócio única; filtre `activity_source_kind`. |
+| Trabalho | `work_items`, `tasks`, `specs`, `prds`, `executions`, `conversations`, `decisions`, `changes` | Views dos snapshots vigentes da fato; nunca tabelas materializadas. |
+| Agent Runs e custo | `agent_runs`, `root_runs`, `sub_runs`, `invocations`, `invocation_usage`, `cost_monitor_*`, `cost_*` | `agent_runs` é a nomenclatura pública; aliases de invocation permanecem apenas para compatibilidade. |
+| Operação e primeira dobra | `operations_*`, `first_fold_*` | Views de trabalho e/ou invocações; usar `LIMIT` na rota consumidora. |
+| Tempo | `daily_aggregate_cache`, `daily_aggregates`, `overview*` | Views calculadas por dia civil de São Paulo; os nomes `*_cache` existem apenas por compatibilidade. |
+
+As seções detalhadas abaixo documentam as colunas expostas por cada objeto. No schema v33, `zaip_aios_activities` é a única tabela física de negócio; `canonical_run_index`, `files`, `read_model_source_state` e `read_model_metadata` são tabelas técnicas reconstruíveis. `canonical_artifacts` e os demais objetos são views. Toda view persistida tem exatamente um prefixo `zaip_vw_`; os nomes curtos deste documento omitem esse prefixo para facilitar a explicação.
+
+- **`NULL` versus zero:** `NULL` significa ausência de valor conhecido e não deve ser convertido em zero sem regra explícita. Contadores `NOT NULL` são numéricos; `task_summary`, `spec_summary` e `prd_summary` declaram `DEFAULT 0` para `invocation_count`.
+- **Custos e estimativas:** `cost_usd`, `cost_brl`, `cost_method`, `pricing_model`, `pricing_source` e `fx_rate` carregam valor e proveniência quando disponíveis. Custos históricos estimados são tratados como fatos canônicos de estimativa, sem serem apresentados como cobrança observada do provedor.
+- **`total_` e `_count`:** `total_` identifica soma no grão da linha; `_count` identifica contagem. Ambos respeitam os filtros e o período aplicados.
+- **Paginação e limites:** há índices de paginação em `task_summary`, `spec_summary` e `prd_summary` por `occurred_at DESC, id`. `LIMIT`, cursor e tamanho de página pertencem à rota ou consulta consumidora, não ao schema persistido. As rotas usam páginas menores para evitar carregar a fato inteira; o ranking da primeira dobra é consumido como Top 5.
+
+## Objetos detalhados
+
+### `activities`
+
+- **Tipo:** View
+- **Finalidade:** Expor todas as linhas atuais da fato `zaip_aios_activities` para as agregações gerais.
+- **Grão/chave:** Uma linha por Run canônico.
+- **Colunas:** As mesmas de `zaip_aios_activities`; a seção da fato documenta cada coluna.
+
+### `canonical_artifacts`
+
+- **Tipo:** View
+- **Finalidade:** Projetar somente Evidence e Validation canônicas já presentes no snapshot técnico `files`, para as contagens diárias, sem materialização própria e sem depender de lifecycle.
+- **Grão/chave:** Uma linha por arquivo canônico de artefato.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `artifact_kind` | `TEXT` | Não nulo | `evidence` ou `validation`. |
+| `artifact_id` | `TEXT` | Não nulo | ID declarado no front matter ou nome canônico do arquivo. |
+| `occurred_at` | `TEXT` | Não nulo | Instante canônico do artefato. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia-calendário calculado no fuso `America/Sao_Paulo`. |
+| `source_path` | `TEXT` | Não nulo; PK | Caminho relativo do arquivo canônico. |
+
+### `canonical_executions`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Indexar os campos escalares de cada `execution.md` canônico para paginação rápida, inclusive quando a Execution ainda não possui Run ou telemetria.
+- **Grão/chave:** Uma linha por `id` de Execution.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não nulo; PK | Identificador canônico da Execution. |
+| `status` | `TEXT` | Sim | Estado persistido no front matter. |
+| `kind` | `TEXT` | Sim | Tipo da Execution, como `delivery` ou `interaction`. |
+| `origin_type` | `TEXT` | Sim | Tipo da origem: task, spec, prd ou interaction. |
+| `origin_id` | `TEXT` | Sim | ID canônico da origem conforme `origin_type`. |
+| `created_at` | `TEXT` | Não nulo | Instante de criação canônico. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia de `created_at` em `America/Sao_Paulo`. |
+| `finished_at` | `TEXT` | Sim | Instante terminal declarado, quando existente. |
+| `source_path` | `TEXT` | Não nulo | Caminho relativo do `execution.md`. |
+
+### `canonical_changes`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Indexar cada `change.md` canônico com o contrato necessário à aba Mudanças, sem ler `lifecycle` nem agregados antigos.
+- **Grão/chave:** Uma linha por `id` de Change.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não nulo; PK | Identificador canônico do Change. |
+| `title` | `TEXT` | Não nulo | Título do Change. |
+| `status` | `TEXT` | Não nulo | Estado canônico. |
+| `risk` | `TEXT` | Não nulo | Risco canônico. |
+| `source_type` | `TEXT` | Não nulo | Tipo da origem: task, spec ou prd. |
+| `source_id` | `TEXT` | Não nulo | ID da origem. |
+| `requirement_ids_json` | `TEXT` | Não nulo | IDs de Requirements serializados como JSON. |
+| `acceptance_ids_json` | `TEXT` | Não nulo | IDs de critérios de aceitação serializados como JSON. |
+| `task_ids_json` | `TEXT` | Não nulo | IDs de Tasks vinculadas serializados como JSON. |
+| `result` | `TEXT` | Sim | Resultado terminal, quando declarado. |
+| `created_at` | `TEXT` | Não nulo | Instante de criação canônico. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia de `created_at` em `America/Sao_Paulo`. |
+| `source_path` | `TEXT` | Não nulo | Caminho relativo do `change.md`. |
+
+### `canonical_decisions`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Indexar Decisions canônicas válidas encontradas nas pastas `decisions/` de Changes e Executions.
+- **Grão/chave:** Uma linha por `id` de Decision.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não nulo; PK | Identificador canônico da Decision. |
+| `title` | `TEXT` | Não nulo | Título da decisão. |
+| `origin` | `TEXT` | Não nulo | Origem `human` ou `agent`. |
+| `scope_type` | `TEXT` | Não nulo | Escopo `change` ou `execution`. |
+| `scope_id` | `TEXT` | Não nulo | ID canônico do escopo. |
+| `created_at` | `TEXT` | Não nulo | Instante de criação canônico. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia de `created_at` em `America/Sao_Paulo`. |
+| `source_path` | `TEXT` | Não nulo | Caminho relativo do Markdown da decisão. |
+
+### `canonical_run_index`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Sustentar cardinalidade, eventos, filtros e tempo oficial diretamente dos Runs canônicos, sem transformar ausência de tokens em zero e sem recolocar esses Runs na fato financeira. A view é descartável e reconstruída junto com o read model; não é uma segunda fato de negócio.
+- **Grão/chave:** Uma linha por `run_id` canônico, tenha ou não tokens e duração conhecidos.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `run_id` | `TEXT` | Não nulo; PK | Identificador canônico e deduplicador do Run. |
+| `occurred_at` | `TEXT` | Não nulo | Instante inicial usado para posicionar o intervalo no calendário. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia-calendário calculado em `America/Sao_Paulo`. |
+| `task_id` | `TEXT` | Sim | Task canônica vinculada, quando houver. |
+| `phase` | `TEXT` | Sim | Fase do Run; somente `execution` entra no KPI oficial de execução. |
+| `run_role` | `TEXT` | Não nulo | Papel estrutural do Run; o KPI oficial usa apenas Runs raiz. |
+| `duration_ms` | `REAL` | Sim | Duração efetiva em milissegundos quando conhecida; intervalos raiz concorrentes são unidos pelas views antes da soma. |
+| `source_event_count` | `INTEGER` | Não nulo | Quantidade observada de eventos canônicos do Run, usada para não transformar ausência de telemetria financeira em zero inventado. |
+| `zaip_agent` | `TEXT` | Sim | Identidade canônica do agente, quando declarada pelo Run. |
+| `provider` | `TEXT` | Sim | Provedor consolidado do Run, quando conhecido. |
+| `model` | `TEXT` | Sim | Modelo consolidado do Run, quando conhecido. |
+| `status` | `TEXT` | Sim | Estado terminal ou corrente observado no Run. |
+
+### `canonical_work_items`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Projetar Tasks, SPECs e PRDs diretamente de seus arquivos Markdown canônicos, inclusive quando ainda não possuem Run. É descartável, reconstruído com o read model e não consome `.agents/records/lifecycle` nem agregados antigos.
+- **Grão/chave:** Uma linha por par `entity_kind` e `id` canônico.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_kind` | `TEXT` | Não nulo; PK | Tipo da entidade: `task`, `spec` ou `prd`. |
+| `id` | `TEXT` | Não nulo; PK | Identificador canônico da entidade dentro do tipo. |
+| `title` | `TEXT` | Sim | Título declarado no front matter canônico. |
+| `status` | `TEXT` | Sim | Estado canônico atual da entidade. |
+| `stage` | `TEXT` | Sim | Etapa canônica, quando declarada. |
+| `risk` | `TEXT` | Sim | Classificação de risco, quando declarada. |
+| `occurred_at` | `TEXT` | Não nulo | Instante canônico usado para posicionar a entidade no calendário. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia-calendário derivado em `America/Sao_Paulo`. |
+
+### `read_model_source_state`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Expor o estado técnico de cada fonte aceita, incluindo seu hash de conteúdo. A decisão de reutilizar o read model compara o fingerprint de caminho, `mtime` e tamanho; portanto ele não deve ser tratado como fingerprint por hash.
+- **Grão/chave:** Uma linha por arquivo-fonte aceito pela allowlist.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `source_path` | `TEXT` | Não nulo; PK | Caminho relativo da fonte canônica. |
+| `source_hash` | `TEXT` | Não nulo | SHA-256 do conteúdo lido. |
+| `mtime_ms` | `INTEGER` | Não nulo | Data de modificação do arquivo em milissegundos Unix. |
+| `size_bytes` | `INTEGER` | Não nulo | Tamanho do arquivo em bytes. |
+| `source_kind` | `TEXT` | Não nulo | `run`, `entity`, `evidence`, `validation` ou `config`. |
+| `last_processed_at` | `TEXT` | Não nulo | Instante em que a fonte foi incorporada à projeção. |
+
+### `changes`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de Changes canônicas, com estado, risco e data.
+- **Grão/chave:** Uma linha por Change.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `conversations`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de Conversations canônicas e seus estados.
+- **Grão/chave:** Uma linha por Conversation.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `cost_monitor_group_daily_cache`
+
+- **Tipo:** View de projeção interna
+- **Finalidade:** Cache privado do agregado diário de duração, tokens e custos por dimensões; não é fonte canônica.
+- **Grão/chave:** Uma linha por dia, tipo de grupo e valor do grupo.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não (`NOT NULL`) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. Chave primária #1. |
+| `group_kind` | `TEXT` | Não (`NOT NULL`) | Dimensão usada no agrupamento diário, como provedor, modelo ou agente. Chave primária #2. |
+| `group_value` | `TEXT` | Não declarado; participa da PK | Valor concreto da dimensão indicada por group_kind; pode ser NULL quando não conhecido. Chave primária #3. |
+| `invocation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `INTEGER` | Permitido pelo DDL | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_input_tokens` | `REAL` | Permitido pelo DDL | Soma dos tokens de entrada conhecidos no grão da linha. |
+| `total_cached_input_tokens` | `REAL` | Permitido pelo DDL | Soma dos tokens de entrada em cache conhecidos no grão da linha. |
+| `total_output_tokens` | `REAL` | Permitido pelo DDL | Soma dos tokens de saída conhecidos no grão da linha. |
+| `total_reasoning_tokens` | `REAL` | Permitido pelo DDL | Soma dos tokens de raciocínio conhecidos no grão da linha. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `cost_monitor_group_daily`
+
+- **Tipo:** View
+- **Finalidade:** Interface pública sobre `cost_monitor_group_daily_cache`; preserva o contrato de leitura do agregado dimensional diário sem expor a cache como fonte canônica.
+- **Grão/chave:** Uma linha por dia, tipo de grupo e valor do grupo.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `group_kind` | `TEXT` | Não determinável (view) | Dimensão usada no agrupamento diário, como provedor, modelo ou agente. |
+| `group_value` | `TEXT` | Não determinável (view) | Valor concreto da dimensão indicada por `group_kind`; pode ser NULL quando não conhecido. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_input_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de entrada conhecidos no grão da linha. |
+| `total_cached_input_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de entrada em cache conhecidos no grão da linha. |
+| `total_output_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de saída conhecidos no grão da linha. |
+| `total_reasoning_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de raciocínio conhecidos no grão da linha. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `cost_monitor_overview`
+
+- **Tipo:** View
+- **Finalidade:** Duração, tokens e custos estimados do Monitor de Custos pré-agregados por período.
+- **Grão/chave:** Uma linha por period_kind e period_key.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não (`NOT NULL`) | Grão temporal do agregado: day, month, year ou all. Chave primária #1. |
+| `period_key` | `TEXT` | Não (`NOT NULL`) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. Chave primária #2. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `daily_aggregates`
+
+- **Tipo:** View
+- **Finalidade:** Interface pública sobre `daily_aggregate_cache`; mantém o contrato de agregados diários sem expor a cache como fonte canônica.
+- **Grão/chave:** Uma linha por dia civil de São Paulo.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Derivado da cache | Dia civil YYYY-MM-DD. |
+| `prd_count` | `INTEGER` | Derivado da cache | Contagem de PRDs. |
+| `spec_count` | `INTEGER` | Derivado da cache | Contagem de SPECs. |
+| `task_count` | `INTEGER` | Derivado da cache | Contagem de Tasks. |
+| `validation_count` | `INTEGER` | Derivado da cache | Contagem de Validations. |
+| `evidence_count` | `INTEGER` | Derivado da cache | Contagem de Evidences. |
+| `invocation_count` | `INTEGER` | Derivado da cache | Contagem de invocações. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Derivado da cache | Duração de relógio das Runs raiz em fase `execution`, em milissegundos. Sub-Runs não são somadas ao pai e intervalos simultâneos são unidos para evitar dupla contagem. |
+| `cost_monitor_total_duration` | `REAL` | Derivado da cache | Duração do Monitor de Custos conhecida. |
+| `total_duration` | `REAL` | Derivado da cache | Soma de durações conhecidas. |
+| `total_tokens` | `REAL` | Derivado da cache | Soma de tokens conhecidos. |
+| `total_cost_usd` | `REAL` | Derivado da cache | Soma de custos USD conhecidos. |
+| `total_cost_brl` | `REAL` | Derivado da cache | Soma de custos BRL conhecidos. |
+
+### `daily_aggregate_cache`
+
+- **Tipo:** View interna
+- **Finalidade:** Agregado diário calculado sob demanda a partir das facts canônicas; não é fonte canônica nem materializa dados.
+- **Grão/chave:** Uma linha por dia civil de São Paulo.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não declarado; participa da PK | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. Chave primária #1. |
+| `prd_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de PRDs canônicos contabilizados no período. |
+| `spec_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de SPECs canônicas contabilizadas no período. |
+| `task_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de Tasks canônicas contabilizadas no período. |
+| `validation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de Validations canônicas contabilizadas no dia. |
+| `evidence_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de Evidences canônicas contabilizadas no dia. |
+| `invocation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `INTEGER` | Permitido pelo DDL | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Permitido pelo DDL | Duração de relógio das Runs raiz em fase `execution`, em milissegundos; exclui Sub-Runs e une intervalos simultâneos. |
+| `cost_monitor_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `decisions`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de Decisions canônicas, com estado, risco e data.
+- **Grão/chave:** Uma linha por Decision.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `dimensions`
+
+- **Tipo:** View
+- **Finalidade:** Valores distintos disponíveis para filtros do dashboard.
+- **Grão/chave:** Uma linha por par dimension e value.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `dimension` | `TEXT` | Não (`NOT NULL`) | Nome da dimensão de filtro, como agente, modelo, provedor, fase ou status. Chave primária #1. |
+| `value` | `TEXT` | Não (`NOT NULL`) | Valor textual associado à chave de metadado ou à dimensão. Chave primária #2. |
+
+### `executions`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de Executions canônicas e seus estados.
+- **Grão/chave:** Uma linha por Execution.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `files`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Cache técnico dos arquivos canônicos lidos, com conteúdo e data de modificação para atualização incremental.
+- **Grão/chave:** Uma linha por caminho relativo de arquivo.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `path` | `TEXT` | Não declarado; participa da PK | Caminho relativo do arquivo canônico acompanhado pela carga incremental. Chave primária #1. |
+| `content` | `TEXT` | Não (`NOT NULL`) | Conteúdo textual integral do arquivo canônico usado pela carga incremental. |
+| `mtime_ms` | `INTEGER` | Não (`NOT NULL`) | Data de modificação do arquivo de origem em milissegundos Unix, usada na atualização incremental. |
+| `size_bytes` | `INTEGER` | Não (`NOT NULL`) | Tamanho do arquivo canônico em bytes. |
+| `content_sha256` | `TEXT` | Não (`NOT NULL`) | Hash SHA-256 do conteúdo, usado para detectar alteração. |
+| `artifact_kind` | `TEXT` | Permitido pelo DDL | `evidence` ou `validation` quando o arquivo é um artefato canônico; caso contrário, `NULL`. |
+| `artifact_id` | `TEXT` | Permitido pelo DDL | ID do artefato extraído do front matter, quando aplicável. |
+| `artifact_occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico do artefato, quando aplicável. |
+| `artifact_occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia do artefato em `America/Sao_Paulo`, quando aplicável. |
+
+### `invocation_usage_segments`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Preservar os segmentos canônicos de uso LLM de Agent Runs com múltiplos provedores ou modelos. Não recebe linhas de turnos sem invocação e não é fonte independente.
+- **Grão/chave:** Uma linha por segmento observado de uma invocação de agente.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `agent_invocation_id` | `TEXT` | Não (`NOT NULL`) | Invocação de agente proprietária do segmento. |
+| `provider` | `TEXT` | Permitido pelo DDL | Provedor observado no segmento. |
+| `model` | `TEXT` | Permitido pelo DDL | Modelo observado no segmento. |
+| `service_tier` | `TEXT` | Permitido pelo DDL | Tier de serviço observado. |
+| `reasoning_effort` | `TEXT` | Permitido pelo DDL | Esforço de raciocínio observado. |
+| `input_tokens` | `REAL` | Permitido pelo DDL | Tokens de entrada do segmento. |
+| `cached_input_tokens` | `REAL` | Permitido pelo DDL | Tokens de entrada em cache do segmento. |
+| `output_tokens` | `REAL` | Permitido pelo DDL | Tokens de saída do segmento. |
+| `reasoning_tokens` | `REAL` | Permitido pelo DDL | Tokens de raciocínio do segmento. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Total de tokens do segmento. |
+| `cost_usd` | `REAL` | Permitido pelo DDL | Custo estimado do segmento em USD. |
+| `cost_brl` | `REAL` | Permitido pelo DDL | Custo estimado do segmento em BRL. |
+| `cost_method` | `TEXT` | Permitido pelo DDL | Método da estimativa. |
+| `pricing_model` | `TEXT` | Permitido pelo DDL | Modelo de precificação aplicado. |
+| `pricing_source` | `TEXT` | Permitido pelo DDL | Fonte da precificação. |
+| `fx_rate` | `REAL` | Permitido pelo DDL | Câmbio USD/BRL aplicado.
+
+
+### `invocation_usage`
+
+- **Tipo:** View
+- **Finalidade:** Segmentos conhecidos de uso LLM de cada invocação, preservando provedor, modelo, tokens, preço e câmbio sem contabilizar desconhecidos.
+- **Grão/chave:** Uma linha por agent_invocation_id e usage_index.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `agent_invocation_id` | `TEXT` | Não (`NOT NULL`) | Identificador global da invocação de agente à qual a linha pertence. Chave primária #1. |
+| `usage_index` | `INTEGER` | Não (`NOT NULL`) | Posição estável do segmento de uso dentro da invocação; compõe a chave primária. Chave primária #2. |
+| `provider` | `TEXT` | Permitido pelo DDL | Provedor LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `model` | `TEXT` | Permitido pelo DDL | Modelo LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `service_tier` | `TEXT` | Permitido pelo DDL | Tier de serviço do provedor associado à chamada, quando conhecido. |
+| `reasoning_effort` | `TEXT` | Permitido pelo DDL | Nível de esforço de raciocínio configurado ou observado para a chamada. |
+| `input_tokens` | `REAL` | Permitido pelo DDL | Tokens de entrada conhecidos no segmento de uso. |
+| `cached_input_tokens` | `REAL` | Permitido pelo DDL | Tokens de entrada reutilizados do cache no segmento de uso. |
+| `output_tokens` | `REAL` | Permitido pelo DDL | Tokens de saída conhecidos no segmento de uso. |
+| `reasoning_tokens` | `REAL` | Permitido pelo DDL | Tokens de raciocínio conhecidos no segmento de uso. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `REAL` | Permitido pelo DDL | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `REAL` | Permitido pelo DDL | Custo estimado em reais atribuído à linha ou segmento. |
+| `cost_method` | `TEXT` | Permitido pelo DDL | Método usado para obter o custo estimado, permitindo interpretar sua proveniência. |
+| `pricing_model` | `TEXT` | Permitido pelo DDL | Modelo de precificação usado na estimativa de custo. |
+| `pricing_source` | `TEXT` | Permitido pelo DDL | Fonte da tabela ou regra de preços usada na estimativa. |
+| `fx_rate` | `REAL` | Permitido pelo DDL | Taxa de câmbio USD para BRL aplicada ao cálculo do custo estimado. |
+
+### `invocations`
+
+- **Tipo v15:** Alias técnico de compatibilidade sobre `agent_runs`. Não é uma tabela materializada nem deve ser a nomenclatura apresentada no dashboard.
+- **Finalidade:** preserva consumidores antigos durante a transição. O nome de negócio é **Agent Run** e a fonte é `zaip_aios_activities` filtrada em `activity_source_kind = 'agent_run'`.
+
+- **Tipo:** View de compatibilidade
+- **Finalidade:** Recorte de Agent Runs da fato, com relações ZAIP, duração, tokens e custos estimados.
+- **Grão/chave:** Uma linha por agent_invocation_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `agent_invocation_id` | `TEXT` | Não declarado; participa da PK | Identificador global da invocação de agente à qual a linha pertence. Chave primária #1. |
+| `summary_hash` | `TEXT` | Não (`NOT NULL`) | Hash do resumo canônico usado para detectar alterações e evitar reprojeções desnecessárias. |
+| `root_agent_invocation_id` | `TEXT` | Não (`NOT NULL`) | Identificador da invocação raiz da árvore à qual a linha pertence. |
+| `parent_agent_invocation_id` | `TEXT` | Permitido pelo DDL | Identificador da invocação pai; NULL identifica uma invocação raiz. |
+| `execution_id` | `TEXT` | Permitido pelo DDL | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `task_id` | `TEXT` | Permitido pelo DDL | Identificador da Task ZAIP associada à linha, quando houver. |
+| `spec_id` | `TEXT` | Permitido pelo DDL | Identificador da SPEC ZAIP associada à linha, quando houver. |
+| `prd_id` | `TEXT` | Permitido pelo DDL | Identificador do PRD ZAIP associado à linha, quando houver. |
+| `change_id` | `TEXT` | Permitido pelo DDL | Identificador da Change ZAIP associada à linha, quando houver. |
+| `conversation_id` | `TEXT` | Permitido pelo DDL | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `run_id` | `TEXT` | Não (`NOT NULL`) | Identificador físico RUN-* que originou a invocação. |
+| `occurred_at` | `TEXT` | Não (`NOT NULL`) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não (`NOT NULL`) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_kind` | `TEXT` | Não (`NOT NULL`) | Tipo da invocação: orquestradora ou delegada, conforme o registro canônico. |
+| `delegation_depth` | `INTEGER` | Não (`NOT NULL`) | Profundidade da invocação na árvore de delegação; zero representa a raiz. |
+| `zaip_agent` | `TEXT` | Permitido pelo DDL | Identidade catalogada do agente ZAIP responsável pela invocação. |
+| `phase` | `TEXT` | Permitido pelo DDL | Fase ZAIP em que a invocação ocorreu. |
+| `purpose` | `TEXT` | Permitido pelo DDL | Propósito operacional da invocação, como orquestração, execução ou finalização. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `duration_ms` | `REAL` | Permitido pelo DDL | Duração conhecida da invocação em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `REAL` | Permitido pelo DDL | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `REAL` | Permitido pelo DDL | Custo estimado em reais atribuído à linha ou segmento. |
+| `cost_method` | `TEXT` | Permitido pelo DDL | Método usado para obter o custo estimado, permitindo interpretar sua proveniência. |
+| `pricing_model` | `TEXT` | Permitido pelo DDL | Modelo de precificação usado na estimativa de custo. |
+| `pricing_source` | `TEXT` | Permitido pelo DDL | Fonte da tabela ou regra de preços usada na estimativa. |
+| `fx_rate` | `REAL` | Permitido pelo DDL | Taxa de câmbio USD para BRL aplicada ao cálculo do custo estimado. |
+| `service_tier` | `TEXT` | Permitido pelo DDL | Tier de serviço do provedor associado à chamada, quando conhecido. |
+| `reasoning_effort` | `TEXT` | Permitido pelo DDL | Nível de esforço de raciocínio configurado ou observado para a chamada. |
+| `source_event_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de eventos canônicos consolidados para formar a invocação. |
+| `llm_call_count` | `INTEGER` | Permitido pelo DDL | Contador canônico de chamadas LLM da invocação; `0` é conhecido e `NULL` significa que a origem não informou a contagem. |
+
+### `operations_overview`
+
+- **Tipo:** View
+- **Finalidade:** Duração total da área Operação pré-agregada por período.
+- **Grão/chave:** Uma linha por period_kind e period_key.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não (`NOT NULL`) | Grão temporal do agregado: day, month, year ou all. Chave primária #1. |
+| `period_key` | `TEXT` | Não (`NOT NULL`) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. Chave primária #2. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pela área Operação no período, em milissegundos. |
+
+### `overview`
+
+- **Tipo:** View
+- **Finalidade:** Agregados consolidados de visão geral nos grãos diário, mensal, anual e todo o período.
+- **Grão/chave:** Uma linha por period_kind e period_key.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não (`NOT NULL`) | Grão temporal do agregado: day, month, year ou all. Chave primária #1. |
+| `period_key` | `TEXT` | Não (`NOT NULL`) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. Chave primária #2. |
+| `start_day` | `TEXT` | Não (`NOT NULL`) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não (`NOT NULL`) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `prd_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de PRDs canônicos contabilizados no período. |
+| `spec_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de SPECs canônicas contabilizadas no período. |
+| `task_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de Tasks canônicas contabilizadas no período. |
+| `invocation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pela área Operação no período, em milissegundos. |
+| `cost_monitor_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `overview_annual`
+
+- **Tipo:** View
+- **Finalidade:** Materialização do recorte anual da visão geral para leitura rápida.
+- **Grão/chave:** Uma linha por ano.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Permitido pelo DDL | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Permitido pelo DDL | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `start_day` | `TEXT` | Permitido pelo DDL | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Permitido pelo DDL | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `prd_count` | `INT` | Permitido pelo DDL | Quantidade de PRDs canônicos contabilizados no período. |
+| `spec_count` | `INT` | Permitido pelo DDL | Quantidade de SPECs canônicas contabilizadas no período. |
+| `task_count` | `INT` | Permitido pelo DDL | Quantidade de Tasks canônicas contabilizadas no período. |
+| `invocation_count` | `INT` | Permitido pelo DDL | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pela área Operação no período, em milissegundos. |
+| `cost_monitor_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `overview_daily`
+
+- **Tipo:** View
+- **Finalidade:** Materialização do recorte diário da visão geral para leitura rápida.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Permitido pelo DDL | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Permitido pelo DDL | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `start_day` | `TEXT` | Permitido pelo DDL | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Permitido pelo DDL | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `prd_count` | `INT` | Permitido pelo DDL | Quantidade de PRDs canônicos contabilizados no período. |
+| `spec_count` | `INT` | Permitido pelo DDL | Quantidade de SPECs canônicas contabilizadas no período. |
+| `task_count` | `INT` | Permitido pelo DDL | Quantidade de Tasks canônicas contabilizadas no período. |
+| `invocation_count` | `INT` | Permitido pelo DDL | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pela área Operação no período, em milissegundos. |
+| `cost_monitor_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `overview_monthly`
+
+- **Tipo:** View
+- **Finalidade:** Materialização do recorte mensal da visão geral para leitura rápida.
+- **Grão/chave:** Uma linha por mês.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Permitido pelo DDL | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Permitido pelo DDL | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `start_day` | `TEXT` | Permitido pelo DDL | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Permitido pelo DDL | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `prd_count` | `INT` | Permitido pelo DDL | Quantidade de PRDs canônicos contabilizados no período. |
+| `spec_count` | `INT` | Permitido pelo DDL | Quantidade de SPECs canônicas contabilizadas no período. |
+| `task_count` | `INT` | Permitido pelo DDL | Quantidade de Tasks canônicas contabilizadas no período. |
+| `invocation_count` | `INT` | Permitido pelo DDL | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pela área Operação no período, em milissegundos. |
+| `cost_monitor_total_duration` | `REAL` | Permitido pelo DDL | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `prd_summary`
+
+- **Tipo:** View
+- **Finalidade:** Resumo por PRD com estado, risco, data e métricas acumuladas de invocações.
+- **Grão/chave:** Uma linha por PRD.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não (`NOT NULL`) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não (`NOT NULL`) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de invocações distintas contabilizadas no grão da linha. Default: `0`. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `prds`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de PRDs canônicos para filtros, relações e consultas detalhadas.
+- **Grão/chave:** Uma linha por PRD.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `read_model_metadata`
+
+- **Tipo:** View técnica reconstruível
+- **Finalidade:** Metadados técnicos do read model, incluindo versão do schema e informações de atualização.
+- **Grão/chave:** Uma linha por chave de metadado.
+- **Chaves emitidas:** `source_file_count`, `excluded_source_count`, `canonical_run_count`, `excluded_unknown_token_run_count`, `activity_count`, `agent_run_count`, `agent_invocation_count`, `unassisted_turn_count`, `telemetry_summary_count`, `daily_aggregate_count`, `schema_version` e `source_fingerprint`. `canonical_run_count` contabiliza a origem; `activity_count` contabiliza somente Runs mensuráveis presentes na fato.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `key` | `TEXT` | Não declarado; participa da PK | Chave textual do metadado técnico do read model. Chave primária #1. |
+| `value` | `TEXT` | Não (`NOT NULL`) | Valor textual associado à chave de metadado ou à dimensão. |
+
+### `spec_summary`
+
+- **Tipo:** View
+- **Finalidade:** Resumo por SPEC com estado, risco, data e métricas acumuladas de invocações.
+- **Grão/chave:** Uma linha por SPEC.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não (`NOT NULL`) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não (`NOT NULL`) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de invocações distintas contabilizadas no grão da linha. Default: `0`. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `specs`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de SPECs canônicas para filtros, relações e consultas detalhadas.
+- **Grão/chave:** Uma linha por SPEC.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `task_summary`
+
+- **Tipo:** View
+- **Finalidade:** Resumo por Task com estado, risco, data e métricas acumuladas de invocações.
+- **Grão/chave:** Uma linha por Task.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não (`NOT NULL`) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não (`NOT NULL`) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não (`NOT NULL`) | Quantidade de invocações distintas contabilizadas no grão da linha. Default: `0`. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Permitido pelo DDL | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Permitido pelo DDL | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Permitido pelo DDL | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `tasks`
+
+- **Tipo:** View
+- **Finalidade:** Dimensão leve de Tasks canônicas para filtros, relações e consultas detalhadas.
+- **Grão/chave:** Uma linha por Task.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `work_items`
+
+- **Tipo:** View
+- **Finalidade:** União calculada de Tasks, SPECs e PRDs para as telas Trabalho Lista e Kanban.
+- **Grão/chave:** Uma linha por entidade unificada.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_kind` | `TEXT` | Não (`NOT NULL`) | Tipo da entidade unificada: task, spec ou prd. |
+| `id` | `TEXT` | Não declarado; participa da PK | Identificador único da entidade representada pela linha. Chave primária #1. |
+| `title` | `TEXT` | Permitido pelo DDL | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Permitido pelo DDL | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Permitido pelo DDL | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Permitido pelo DDL | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Permitido pelo DDL | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `cost_monitor_agent_invocations`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_agent_invocations; Detalhe de invocações com provedor e modelo consolidados; usa mixed quando há mais de um valor conhecido.
+- **Grão/chave:** Uma linha por agent_invocation_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador global da invocação de agente à qual a linha pertence. |
+| `summary_hash` | `TEXT` | Não determinável (view) | Hash do resumo canônico usado para detectar alterações e evitar reprojeções desnecessárias. |
+| `root_agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador da invocação raiz da árvore à qual a linha pertence. |
+| `parent_agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador da invocação pai; NULL identifica uma invocação raiz. |
+| `execution_id` | `TEXT` | Não determinável (view) | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `task_id` | `TEXT` | Não determinável (view) | Identificador da Task ZAIP associada à linha, quando houver. |
+| `spec_id` | `TEXT` | Não determinável (view) | Identificador da SPEC ZAIP associada à linha, quando houver. |
+| `prd_id` | `TEXT` | Não determinável (view) | Identificador do PRD ZAIP associado à linha, quando houver. |
+| `change_id` | `TEXT` | Não determinável (view) | Identificador da Change ZAIP associada à linha, quando houver. |
+| `conversation_id` | `TEXT` | Não determinável (view) | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `title` | `TEXT` | Não determinável (view) | Título exibível; usa o identificador quando não há título canônico separado. |
+| `status` | `TEXT` | Não determinável (view) | Último status canônico conhecido da conversa. |
+| `risk` | `derivada (sem afinidade declarada)` | Não determinável (view) | Nulo para conversas, que não possuem risco de lifecycle próprio. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Primeiro instante canônico conhecido no agrupamento. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil de `occurred_at` em `America/Sao_Paulo`. |
+| `total_duration` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma das durações conhecidas das invocações da conversa, em milissegundos. |
+| `run_id` | `TEXT` | Não determinável (view) | Identificador físico RUN-* que originou a invocação. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_kind` | `TEXT` | Não determinável (view) | Tipo da invocação: orquestradora ou delegada, conforme o registro canônico. |
+| `delegation_depth` | `INTEGER` | Não determinável (view) | Profundidade da invocação na árvore de delegação; zero representa a raiz. |
+| `zaip_agent` | `TEXT` | Não determinável (view) | Identidade catalogada do agente ZAIP responsável pela invocação. |
+| `phase` | `TEXT` | Não determinável (view) | Fase ZAIP em que a invocação ocorreu. |
+| `purpose` | `TEXT` | Não determinável (view) | Propósito operacional da invocação, como orquestração, execução ou finalização. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `source_duration_ms` | `REAL` | Não determinável (view) | Duração factual observada na fonte; pode ser NULL mesmo quando `duration_ms` possui uma reconciliação ou estimativa confiável. |
+| `duration_ms` | `REAL` | Não determinável (view) | Tempo total da invocação em milissegundos, usando a melhor duração canônica disponível. |
+| `duration_provenance` | `TEXT` | Não determinável (view) | Origem do tempo total: `observed`, `reconciled`, `legacy_inferred` ou `estimated`. |
+| `input_tokens` | `REAL` | Não determinável (view) | Tokens de entrada totais; inclui a parcela servida pelo cache. |
+| `cached_input_tokens` | `REAL` | Não determinável (view) | Parcela dos tokens de entrada servida pelo cache. |
+| `uncached_input_tokens` | `REAL` | Não determinável (view) | Parcela cobrada à tarifa cheia: `MAX(input_tokens - cached_input_tokens, 0)`. |
+| `output_tokens` | `REAL` | Não determinável (view) | Tokens de saída totais; já incluem reasoning conforme o contrato do provedor. |
+| `reasoning_tokens` | `REAL` | Não determinável (view) | Subconjunto informativo dos tokens de saída usado para auditoria; não é somado novamente ao custo. |
+| `visible_output_tokens` | `REAL` | Não determinável (view) | Parcela visível da saída: `MAX(output_tokens - reasoning_tokens, 0)`. |
+| `total_tokens` | `REAL` | Não determinável (view) | Total canônico informado pelo provedor; não deve ser recalculado somando reasoning ao output. |
+| `input_rate_usd_per_million` | `REAL` | Não determinável (view) | Tarifa efetiva em USD por milhão de tokens de input sem cache. |
+| `cached_input_rate_usd_per_million` | `REAL` | Não determinável (view) | Tarifa efetiva em USD por milhão de tokens de input em cache. |
+| `output_rate_usd_per_million` | `REAL` | Não determinável (view) | Tarifa efetiva em USD por milhão de tokens de output. |
+| `reasoning_rate_usd_per_million` | `REAL` | Não determinável (view) | Tarifa de referência para reasoning; o custo separado permanece zero quando reasoning já está contido em output. |
+| `context_input_multiplier` | `REAL` | Não determinável (view) | Multiplicador de contexto aplicado às parcelas de input e cache. |
+| `context_output_multiplier` | `REAL` | Não determinável (view) | Multiplicador de contexto aplicado ao output. |
+| `speed_cost_multiplier` | `REAL` | Não determinável (view) | Relação entre o cenário de velocidade efetivo e o cenário Standard. |
+| `pricing_scenario` | `TEXT` | Não determinável (view) | Cenário auditado: `standard`, `priority`, `standard_long_context_fallback` ou `mixed`. |
+| `input_cost_usd` | `REAL` | Não determinável (view) | `(uncached_input_tokens / 1.000.000) × tarifa input × multiplicador de contexto input`. |
+| `cached_input_cost_usd` | `REAL` | Não determinável (view) | `(cached_input_tokens / 1.000.000) × tarifa cache × multiplicador de contexto input`. |
+| `output_cost_usd` | `REAL` | Não determinável (view) | `(output_tokens / 1.000.000) × tarifa output × multiplicador de contexto output`. |
+| `reasoning_cost_usd` | `REAL` | Não determinável (view) | Zero quando reasoning é subconjunto do output, evitando dupla cobrança. |
+| `calculated_cost_usd` | `REAL` | Não determinável (view) | Soma auditável de input, cache, output e reasoning segundo o Guide. |
+| `recorded_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos USD explicitamente presentes nos eventos canônicos; pode ser NULL quando o custo foi estimado. |
+| `cost_variance_usd` | `REAL` | Não determinável (view) | Diferença `recorded_cost_usd - calculated_cost_usd`, útil para auditar estimativas históricas. |
+| `cost_usd` | `REAL` | Não determinável (view) | Custo canônico efetivo em USD usado pelos totais do dashboard. |
+| `fx_rate` | `REAL` | Não determinável (view) | Taxa USD/BRL aplicada ao custo efetivo. |
+| `cost_brl` | `REAL` | Não determinável (view) | Custo canônico efetivo em BRL. |
+| `pricing_segment_count` | `INTEGER` | Não determinável (view) | Quantidade de segmentos canônicos de uso agregados sem expor cada chamada LLM como linha. |
+| `pricing_mixed` | `INTEGER` | Não determinável (view) | `1` quando a invocação combina mais de uma configuração de preço; nesse caso tarifas únicas podem ser NULL. |
+| `cost_method` | `TEXT` | Não determinável (view) | Método usado para obter o custo estimado, permitindo interpretar sua proveniência. |
+| `pricing_model` | `TEXT` | Não determinável (view) | Modelo de precificação usado na estimativa de custo. |
+| `pricing_source` | `TEXT` | Não determinável (view) | Fonte da tabela ou regra de preços usada na estimativa. |
+| `fx_rate` | `REAL` | Não determinável (view) | Taxa de câmbio USD para BRL aplicada ao cálculo do custo estimado. |
+| `service_tier` | `TEXT` | Não determinável (view) | Tier de serviço do provedor associado à chamada, quando conhecido. |
+| `reasoning_effort` | `TEXT` | Não determinável (view) | Nível de esforço de raciocínio configurado ou observado para a chamada. |
+| `source_event_count` | `INTEGER` | Não determinável (view) | Quantidade de eventos canônicos consolidados para formar a invocação. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `provider` | `derivada (sem afinidade declarada)` | Não determinável (view) | Provedor LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `model` | `derivada (sem afinidade declarada)` | Não determinável (view) | Modelo LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+
+### `cost_monitor_annual`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_annual; Métricas anuais de duração, tokens e custos estimados, com início e fim do período.
+- **Grão/chave:** Uma linha por ano.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_monitor_conversations`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_conversations; Tokens, custos estimados e invocações agregados por Conversation.
+- **Grão/chave:** Uma linha por conversation_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `conversation_id` | `TEXT` | Não determinável (view) | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_daily`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_daily; Métricas diárias de duração, tokens e custos estimados, com início e fim do período.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_monitor_executions`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_executions; Tokens, custos estimados e quantidade de invocações agregados por Execution.
+- **Grão/chave:** Uma linha por execution_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `execution_id` | `TEXT` | Não determinável (view) | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `title` | `TEXT` | Não determinável (view) | Título exibível da Execution; por padrão, o próprio identificador. |
+| `status` | `TEXT` | Não determinável (view) | Último status canônico conhecido da Execution. |
+| `risk` | `derivada (sem afinidade declarada)` | Não determinável (view) | Nulo nesta visão; risco pertence aos itens de trabalho associados. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Primeiro instante canônico conhecido no agrupamento. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil de `occurred_at` em `America/Sao_Paulo`. |
+| `total_duration` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma das durações conhecidas das invocações da Execution, em milissegundos. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_models`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_models; Tokens, custos estimados e invocações distintas agregados por modelo conhecido.
+- **Grão/chave:** Uma linha por modelo LLM.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `model` | `TEXT` | Não determinável (view) | Modelo LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_monthly`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_monthly; Métricas mensais de duração, tokens e custos estimados, com início e fim do período.
+- **Grão/chave:** Uma linha por mês.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_monitor_overview_view`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_overview; Métricas do Monitor de Custos para todos os grãos temporais.
+- **Grão/chave:** Uma linha por período.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_monitor_prds`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_prds; Tokens, custos estimados e invocações agregados por PRD.
+- **Grão/chave:** Uma linha por prd_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `prd_id` | `TEXT` | Não determinável (view) | Identificador do PRD ZAIP associado à linha, quando houver. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico do PRD. |
+| `status` | `TEXT` | Não determinável (view) | Status canônico conhecido do PRD. |
+| `risk` | `TEXT` | Não determinável (view) | Risco canônico conhecido do PRD. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Primeiro instante canônico conhecido no agrupamento. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil de `occurred_at` em `America/Sao_Paulo`. |
+| `total_duration` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma das durações conhecidas das invocações do PRD, em milissegundos. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_providers`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_providers; Tokens, custos estimados e invocações distintas agregados por provedor conhecido.
+- **Grão/chave:** Uma linha por provedor LLM.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `provider` | `TEXT` | Não determinável (view) | Provedor LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_specs`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_specs; Tokens, custos estimados e invocações agregados por SPEC.
+- **Grão/chave:** Uma linha por spec_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `spec_id` | `TEXT` | Não determinável (view) | Identificador da SPEC ZAIP associada à linha, quando houver. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico da SPEC. |
+| `status` | `TEXT` | Não determinável (view) | Status canônico conhecido da SPEC. |
+| `risk` | `TEXT` | Não determinável (view) | Risco canônico conhecido da SPEC. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Primeiro instante canônico conhecido no agrupamento. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil de `occurred_at` em `America/Sao_Paulo`. |
+| `total_duration` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma das durações conhecidas das invocações da SPEC, em milissegundos. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_tasks`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_tasks; Tokens, custos estimados e invocações agregados por Task.
+- **Grão/chave:** Uma linha por task_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `task_id` | `TEXT` | Não determinável (view) | Identificador da Task ZAIP associada à linha, quando houver. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico da Task. |
+| `status` | `TEXT` | Não determinável (view) | Status canônico conhecido da Task. |
+| `risk` | `TEXT` | Não determinável (view) | Risco canônico conhecido da Task. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Primeiro instante canônico conhecido no agrupamento. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil de `occurred_at` em `America/Sao_Paulo`. |
+| `total_duration` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma das durações conhecidas das invocações da Task, em milissegundos. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monitor_zaip_agents`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_cost_zaip_agents; Tokens, custos estimados e invocações agregados por identidade de agente.
+- **Grão/chave:** Uma linha por agente ZAIP.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `zaip_agent` | `TEXT` | Não determinável (view) | Identidade catalogada do agente ZAIP responsável pela invocação. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `first_fold_spec_status_all_time`
+
+- **Tipo:** Views
+- **Finalidade:** Distribuição completa por estágio exibida ao selecionar SPEC ou PRD.
+- **Grão/chave:** Uma linha por `stage` e tipo de macro.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `stage` | `TEXT` | Não determinável (view) | Estágio operacional normalizado: definition, planning, ready, executing, verifying ou terminal. |
+| `entity_count` | `INTEGER` | Não determinável (view) | Quantidade de SPECs ou PRDs no estágio. |
+| `entity_percentage` | `REAL` | Não determinável (view) | Participação do estágio na população do tipo, de 0 a 1. |
+
+### `first_fold_prd_status_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Mesmo contrato de status global, aplicado à população de PRDs.
+- **Grão/chave:** Uma linha por `stage`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `stage` | `TEXT` | Não determinável (view) | Estágio operacional normalizado do PRD. |
+| `entity_count` | `INTEGER` | Não determinável (view) | Quantidade de PRDs no estágio. |
+| `entity_percentage` | `REAL` | Não determinável (view) | Participação do estágio no total de PRDs, de 0 a 1. |
+
+### `first_fold_spec_classification_all_time`
+
+- **Tipo:** Views
+- **Finalidade:** Classificação completa dos macros por presença de Tasks e retrabalho.
+- **Grão/chave:** Uma linha por `classification` e tipo de macro.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `classification` | `TEXT` | Não determinável (view) | `empty` sem Tasks, `structured` com Tasks e `rework` quando existe Run raiz de retrabalho. |
+| `entity_count` | `INTEGER` | Não determinável (view) | Quantidade de SPECs ou PRDs na classificação. |
+| `entity_percentage` | `REAL` | Não determinável (view) | Participação da classificação na população do tipo, de 0 a 1. |
+
+### `first_fold_prd_classification_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Mesmo contrato de classificação global, aplicado à população de PRDs.
+- **Grão/chave:** Uma linha por `classification`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `classification` | `TEXT` | Não determinável (view) | `empty`, `structured` ou `rework`. |
+| `entity_count` | `INTEGER` | Não determinável (view) | Quantidade de PRDs na classificação. |
+| `entity_percentage` | `REAL` | Não determinável (view) | Participação da classificação no total de PRDs, de 0 a 1. |
+
+### `first_fold_spec_metrics_all_time`
+
+- **Tipo:** Views
+- **Finalidade:** Totais e médias usados pelo card “Média por SPEC/PRD”.
+- **Grão/chave:** Uma linha para toda a população do tipo.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_count` | `INTEGER` | Não determinável (view) | Quantidade total de macros do tipo. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Quantidade de atividades canônicas vinculadas. |
+| `total_duration_ms` | `REAL` | Não determinável (view) | Duração acumulada das Runs raiz, em todas as fases, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos vinculados ao tipo. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em USD. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em BRL. |
+| `average_duration_ms` | `REAL` | Não determinável (view) | Duração média por macro, em milissegundos. |
+| `average_tokens` | `REAL` | Não determinável (view) | Tokens médios por macro. |
+| `average_cost_usd` | `REAL` | Não determinável (view) | Custo estimado médio em USD por macro. |
+| `average_cost_brl` | `REAL` | Não determinável (view) | Custo estimado médio em BRL por macro. |
+| `latest_created_at` | `TEXT` | Não determinável (view) | Instante canônico mais recente associado à criação de um macro do tipo. |
+
+### `first_fold_prd_metrics_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Mesmo contrato de totais e médias, aplicado à população de PRDs.
+- **Grão/chave:** Uma linha para todos os PRDs.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_count` | `INTEGER` | Não determinável (view) | Quantidade total de PRDs. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Quantidade de atividades canônicas vinculadas. |
+| `total_duration_ms` | `REAL` | Não determinável (view) | Duração acumulada das Runs raiz, em todas as fases, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados em USD. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados em BRL. |
+| `average_duration_ms` | `REAL` | Não determinável (view) | Duração média por PRD, em milissegundos. |
+| `average_tokens` | `REAL` | Não determinável (view) | Tokens médios por PRD. |
+| `average_cost_usd` | `REAL` | Não determinável (view) | Custo estimado médio em USD por PRD. |
+| `average_cost_brl` | `REAL` | Não determinável (view) | Custo estimado médio em BRL por PRD. |
+| `latest_created_at` | `TEXT` | Não determinável (view) | Instante canônico mais recente associado à criação de PRD. |
+
+### `first_fold_top_specs_all_time`
+
+- **Tipo:** Views
+- **Finalidade:** Top 5 pronto para os gráficos de SPEC e PRD.
+- **Grão/chave:** Até cinco linhas por tipo, ordenadas por `rank`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `rank` | `INTEGER` | Não determinável (view) | Posição de 1 a 5; duração conhecida vem antes de indisponível. |
+| `entity_id` | `TEXT` | Não determinável (view) | Identificador canônico da SPEC ou PRD. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico do macro. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico do macro. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Quantidade de atividades canônicas vinculadas. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Soma das chamadas LLM conhecidas. |
+| `total_duration_ms` | `REAL` | Não determinável (view) | Duração acumulada das Runs raiz em todas as fases, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados em USD. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados em BRL. |
+| `duration_share` | `REAL` | Não determinável (view) | Participação do macro na duração conhecida do tipo, de 0 a 1. |
+
+### `first_fold_top_prds_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Top 5 de PRDs pronto para a primeira dobra.
+- **Grão/chave:** Até cinco linhas, ordenadas por `rank`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `rank` | `INTEGER` | Não determinável (view) | Posição de 1 a 5. |
+| `entity_id` | `TEXT` | Não determinável (view) | Identificador canônico do PRD. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico do PRD. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico do PRD. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Quantidade de atividades vinculadas. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Soma das chamadas LLM conhecidas. |
+| `total_duration_ms` | `REAL` | Não determinável (view) | Duração acumulada das Runs raiz em todas as fases, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados em USD. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados em BRL. |
+| `duration_share` | `REAL` | Não determinável (view) | Participação do PRD na duração conhecida de todos os PRDs, de 0 a 1. |
+
+### `first_fold_overview_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Alimenta os big numbers da abertura em Todo o Período com uma única linha já agregada.
+- **Grão/chave:** Uma linha identificada por `period_key = 'all'`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_key` | `TEXT` | Não determinável (view) | Chave constante `all` do período integral. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia canônico incluído, em `YYYY-MM-DD`. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia canônico incluído, em `YYYY-MM-DD`. |
+| `task_count` | `INTEGER` | Não determinável (view) | Quantidade total de Tasks canônicas. |
+| `completed_task_count` | `INTEGER` | Não determinável (view) | Quantidade total de Tasks concluídas. |
+| `spec_count` | `INTEGER` | Não determinável (view) | Quantidade total de SPECs canônicas. |
+| `completed_spec_count` | `INTEGER` | Não determinável (view) | Quantidade total de SPECs concluídas. |
+| `prd_count` | `INTEGER` | Não determinável (view) | Quantidade total de PRDs canônicos. |
+| `completed_prd_count` | `INTEGER` | Não determinável (view) | Quantidade total de PRDs concluídos. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Soma de Runs raiz contabilizadas nos agregados diários. |
+| `agent_invocation_count` | `INTEGER` | Não determinável (view) | Soma das invocações de agentes conhecidas. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Soma das chamadas LLM conhecidas. |
+| `total_duration_ms` | `REAL` | Não determinável (view) | Duração oficial desduplicada em milissegundos; dividir por `3.600.000` para horas. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados em USD. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados em BRL. |
+| `execution_day_count` | `INTEGER` | Não determinável (view) | Quantidade de dias com duração operacional conhecida. |
+| `latest_task_created_at` | `TEXT` | Não determinável (view) | Instante da Task canônica mais recente. |
+
+### `first_fold_task_status_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Alimenta o gráfico global de status sem ler todas as Tasks.
+- **Grão/chave:** Uma linha por `status`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `status` | `TEXT` | Não determinável (view) | Estado canônico da Task; ausência é normalizada como `draft`. |
+| `task_count` | `INTEGER` | Não determinável (view) | Quantidade de Tasks no status. |
+| `task_percentage` | `REAL` | Não determinável (view) | Participação do status no total, de 0 a 1. |
+
+### `first_fold_task_risk_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Alimenta o gráfico global de classificação sem ler todas as Tasks.
+- **Grão/chave:** Uma linha por `risk`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco; ausência é normalizada como `standard`. |
+| `task_count` | `INTEGER` | Não determinável (view) | Quantidade de Tasks na classificação. |
+| `task_percentage` | `REAL` | Não determinável (view) | Participação da classificação no total, de 0 a 1. |
+
+### `first_fold_task_metrics_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Fornece as médias globais por Task e a última criação em uma linha.
+- **Grão/chave:** Uma linha para todo o histórico.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `task_count` | `INTEGER` | Não determinável (view) | Denominador canônico das médias. |
+| `average_duration_ms_per_task` | `REAL` | Não determinável (view) | Duração média oficial por Task, em milissegundos. |
+| `average_tokens_per_task` | `REAL` | Não determinável (view) | Tokens médios conhecidos por Task. |
+| `average_cost_usd_per_task` | `REAL` | Não determinável (view) | Custo estimado médio em USD por Task. |
+| `average_cost_brl_per_task` | `REAL` | Não determinável (view) | Custo estimado médio em BRL por Task. |
+| `latest_task_created_at` | `TEXT` | Não determinável (view) | Instante da Task canônica mais recente. |
+
+### `first_fold_top_tasks_all_time`
+
+- **Tipo:** View
+- **Finalidade:** Entrega diretamente o Top 5 global para o bloco da primeira dobra.
+- **Grão/chave:** Até cinco linhas, identificadas por `rank` e `task_id`.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `rank` | `INTEGER` | Não determinável (view) | Posição de 1 a 5 por duração decrescente. |
+| `task_id` | `TEXT` | Não determinável (view) | Identificador canônico da Task. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico da Task. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico da Task. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco da Task. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Quantidade de atividades de execução atribuídas à Task. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Soma das chamadas LLM conhecidas da Task. |
+| `total_duration_ms` | `REAL` | Não determinável (view) | Duração oficial desduplicada da Task em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos da Task. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados em USD da Task. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados em BRL da Task. |
+| `duration_share` | `REAL` | Não determinável (view) | Participação da Task na duração total das Tasks com tempo conhecido, de 0 a 1. |
+
+### `first_fold_overview`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_overview; Projeção compacta da visão geral usada nos big numbers da primeira dobra.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `prd_count` | `INTEGER` | Não determinável (view) | Quantidade de PRDs canônicos contabilizados no período. |
+| `spec_count` | `INTEGER` | Não determinável (view) | Quantidade de SPECs canônicas contabilizadas no período. |
+| `task_count` | `INTEGER` | Não determinável (view) | Quantidade de Tasks canônicas contabilizadas no período. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `operations_total_duration` | `REAL` | Não determinável (view) | Duração total usada pela área Operação no período, em milissegundos. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `first_fold_prd`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_prd_summary; Resumo compacto de PRDs para a primeira dobra.
+- **Grão/chave:** Uma linha por PRD.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `first_fold_spec`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_spec_summary; Resumo compacto de SPECs para a primeira dobra.
+- **Grão/chave:** Uma linha por SPEC.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `first_fold_task`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_task_summary; Resumo compacto de Tasks para a primeira dobra.
+- **Grão/chave:** Uma linha por Task.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `first_fold_task_risk`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_task_risk; Série compacta para o gráfico de risco de Tasks na primeira dobra.
+- **Grão/chave:** Uma linha por dia e risco.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `task_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de Tasks canônicas contabilizadas no período. |
+
+### `first_fold_task_status`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_task_status; Série compacta para o gráfico de status de Tasks na primeira dobra.
+- **Grão/chave:** Uma linha por dia e status.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `task_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de Tasks canônicas contabilizadas no período. |
+
+### `first_fold_top_tasks`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_first_fold_top_tasks; Ranking de Tasks com duração, tokens e custos acumulados; o consumidor aplica o limite Top 5.
+- **Grão/chave:** Uma linha por Task, ordenada por duração decrescente.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `total_duration:1` | `derivada (sem afinidade declarada)` | Não determinável (view) | Segunda projeção homônima de total_duration criada pelo SELECT da view; contém o mesmo agregado de duração. |
+| `total_tokens:1` | `derivada (sem afinidade declarada)` | Não determinável (view) | Segunda projeção homônima de total_tokens criada pelo SELECT da view; contém o mesmo agregado de tokens. |
+| `total_cost_usd:1` | `derivada (sem afinidade declarada)` | Não determinável (view) | Segunda projeção homônima de total_cost_usd criada pelo SELECT da view; contém o mesmo agregado de custo em USD. |
+| `total_cost_brl:1` | `derivada (sem afinidade declarada)` | Não determinável (view) | Segunda projeção homônima de total_cost_brl criada pelo SELECT da view; contém o mesmo agregado de custo em BRL. |
+
+### `operations_agent_invocations`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_agent_invocations; Invocações de agentes enriquecidas com risco da Task para a área Operação.
+- **Grão/chave:** Uma linha por agent_invocation_id.
+- **Auditoria financeira:** expõe o mesmo contrato de tokens, tarifas, multiplicadores, parcelas, cenário e diferença documentado em `cost_monitor_agent_invocations`; segmentos técnicos são somados antes da exibição.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador global da invocação de agente à qual a linha pertence. |
+| `summary_hash` | `TEXT` | Não determinável (view) | Hash do resumo canônico usado para detectar alterações e evitar reprojeções desnecessárias. |
+| `root_agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador da invocação raiz da árvore à qual a linha pertence. |
+| `parent_agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador da invocação pai; NULL identifica uma invocação raiz. |
+| `execution_id` | `TEXT` | Não determinável (view) | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `task_id` | `TEXT` | Não determinável (view) | Identificador da Task ZAIP associada à linha, quando houver. |
+| `spec_id` | `TEXT` | Não determinável (view) | Identificador da SPEC ZAIP associada à linha, quando houver. |
+| `prd_id` | `TEXT` | Não determinável (view) | Identificador do PRD ZAIP associado à linha, quando houver. |
+| `change_id` | `TEXT` | Não determinável (view) | Identificador da Change ZAIP associada à linha, quando houver. |
+| `conversation_id` | `TEXT` | Não determinável (view) | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `run_id` | `TEXT` | Não determinável (view) | Identificador físico RUN-* que originou a invocação. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_kind` | `TEXT` | Não determinável (view) | Tipo da invocação: orquestradora ou delegada, conforme o registro canônico. |
+| `delegation_depth` | `INTEGER` | Não determinável (view) | Profundidade da invocação na árvore de delegação; zero representa a raiz. |
+| `zaip_agent` | `TEXT` | Não determinável (view) | Identidade catalogada do agente ZAIP responsável pela invocação. |
+| `phase` | `TEXT` | Não determinável (view) | Fase ZAIP em que a invocação ocorreu. |
+| `purpose` | `TEXT` | Não determinável (view) | Propósito operacional da invocação, como orquestração, execução ou finalização. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `duration_ms` | `REAL` | Não determinável (view) | Duração conhecida da invocação em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `REAL` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `REAL` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `cost_method` | `TEXT` | Não determinável (view) | Método usado para obter o custo estimado, permitindo interpretar sua proveniência. |
+| `pricing_model` | `TEXT` | Não determinável (view) | Modelo de precificação usado na estimativa de custo. |
+| `pricing_source` | `TEXT` | Não determinável (view) | Fonte da tabela ou regra de preços usada na estimativa. |
+| `fx_rate` | `REAL` | Não determinável (view) | Taxa de câmbio USD para BRL aplicada ao cálculo do custo estimado. |
+| `service_tier` | `TEXT` | Não determinável (view) | Tier de serviço do provedor associado à chamada, quando conhecido. |
+| `reasoning_effort` | `TEXT` | Não determinável (view) | Nível de esforço de raciocínio configurado ou observado para a chamada. |
+| `source_event_count` | `INTEGER` | Não determinável (view) | Quantidade de eventos canônicos consolidados para formar a invocação. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `provider` | `derivada (sem afinidade declarada)` | Não determinável (view) | Provedor LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `model` | `derivada (sem afinidade declarada)` | Não determinável (view) | Modelo LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+
+### `operations_annual`
+
+- **Tipo:** View
+- **Finalidade:** Resumo anual completo da área Operação, derivado das fontes canônicas.
+- **Grão/chave:** Uma linha por ano.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month ou year. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave YYYY-MM-DD, YYYY-MM ou YYYY conforme o grão. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil de São Paulo incluído no período. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil de São Paulo incluído no período. |
+| `prd_count` | `INTEGER` | Não determinável (view) | PRDs canônicos criados no período. |
+| `spec_count` | `INTEGER` | Não determinável (view) | SPECs canônicas criadas no período. |
+| `task_count` | `INTEGER` | Não determinável (view) | Tasks canônicas criadas no período. |
+| `validation_count` | `INTEGER` | Não determinável (view) | Validações canônicas registradas no período. |
+| `evidence_count` | `INTEGER` | Não determinável (view) | Evidências canônicas registradas no período. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Total de Runs raiz e Sub-Runs canônicos iniciados no período. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Atividades de agente com telemetria contabilizadas no período. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Chamadas LLM conhecidas no período; NULL quando indisponível. |
+| `operations_total_duration` | `REAL` | Não determinável (view) | União dos intervalos de execução no período, em milissegundos, sem dupla contagem de sobreposições. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos no período. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma do custo estimado em USD no período. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma do custo estimado em BRL no período. |
+
+### `operations_changes`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_changes; Projeção de Changes para a aba Operação.
+- **Grão/chave:** Uma linha por Change.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico do Change. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `source_type` | `TEXT` | Não determinável (view) | Tipo da origem canônica: task, spec ou prd. |
+| `source_id` | `TEXT` | Não determinável (view) | ID da origem canônica. |
+| `requirement_ids_json` | `TEXT` | Não determinável (view) | Requirements vinculados serializados como JSON. |
+| `acceptance_ids_json` | `TEXT` | Não determinável (view) | Critérios de aceitação vinculados serializados como JSON. |
+| `task_ids_json` | `TEXT` | Não determinável (view) | Tasks vinculadas serializadas como JSON. |
+| `result` | `TEXT` | Não determinável (view) | Resultado terminal, quando existente. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `source_path` | `TEXT` | Não determinável (view) | Caminho relativo do `change.md` canônico. |
+
+### `operations_conversations`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_conversations; Conversations com estado, risco consolidado, intervalo, duração e quantidade de invocações.
+- **Grão/chave:** Uma linha por conversation_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `conversation_id` | `TEXT` | Não determinável (view) | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `derivada (sem afinidade declarada)` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `started_at` | `derivada (sem afinidade declarada)` | Não determinável (view) | Primeiro instante observado no grupo, em formato temporal ISO. |
+| `finished_at` | `derivada (sem afinidade declarada)` | Não determinável (view) | Último instante observado no grupo, em formato temporal ISO. |
+| `total_duration` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos tokens conhecidos da Conversation. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma do custo estimado em BRL da Conversation. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `operations_daily`
+
+- **Tipo:** View
+- **Finalidade:** Resumo diário completo da área Operação, derivado das fontes canônicas.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal day. |
+| `period_key` | `TEXT` | Não determinável (view) | Mesma chave YYYY-MM-DD exposta em day. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia incluído; igual a day no grão diário. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia incluído; igual a day no grão diário. |
+| `prd_count` | `INTEGER` | Não determinável (view) | PRDs canônicos criados no dia. |
+| `spec_count` | `INTEGER` | Não determinável (view) | SPECs canônicas criadas no dia. |
+| `task_count` | `INTEGER` | Não determinável (view) | Tasks canônicas criadas no dia. |
+| `validation_count` | `INTEGER` | Não determinável (view) | Validações canônicas registradas no dia. |
+| `evidence_count` | `INTEGER` | Não determinável (view) | Evidências canônicas registradas no dia. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Total de Runs raiz e Sub-Runs canônicos iniciados no dia. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Atividades de agente com telemetria contabilizadas no dia. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Chamadas LLM conhecidas no dia; NULL quando indisponível. |
+| `operations_total_duration` | `REAL` | Não determinável (view) | União dos intervalos de execução do dia, em milissegundos, sem dupla contagem de sobreposições. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos no dia. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma do custo estimado em USD no dia. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma do custo estimado em BRL no dia. |
+
+### `operations_decisions`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_decisions; Projeção de Decisions para a aba Operação.
+- **Grão/chave:** Uma linha por Decision.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título canônico da Decision. |
+| `origin` | `TEXT` | Não determinável (view) | Origem `human` ou `agent`. |
+| `scope_type` | `TEXT` | Não determinável (view) | Tipo de escopo `change` ou `execution`. |
+| `scope_id` | `TEXT` | Não determinável (view) | ID canônico do escopo. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `source_path` | `TEXT` | Não determinável (view) | Caminho relativo do Markdown canônico da Decision. |
+
+### `operations_executions`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_executions; Executions com estado, risco consolidado, intervalo, duração e quantidade de invocações.
+- **Grão/chave:** Uma linha por execution_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `execution_id` | `TEXT` | Não determinável (view) | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `derivada (sem afinidade declarada)` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `started_at` | `derivada (sem afinidade declarada)` | Não determinável (view) | Primeiro instante observado no grupo, em formato temporal ISO. |
+| `finished_at` | `derivada (sem afinidade declarada)` | Não determinável (view) | Último instante observado no grupo, em formato temporal ISO. |
+| `execution_kind` | `TEXT` | Não determinável (view) | Tipo canônico da Execution. |
+| `origin_type` | `TEXT` | Não determinável (view) | Tipo da origem canônica. |
+| `task_id` | `TEXT` | Não determinável (view) | Task de origem, quando aplicável. |
+| `conversation_id` | `TEXT` | Não determinável (view) | Conversation de origem, quando aplicável. |
+| `duration_ms` | `derivada (sem afinidade declarada)` | Não determinável (view) | Duração conhecida da invocação em milissegundos. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos tokens conhecidos da Execution. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma do custo estimado em BRL da Execution. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `source_path` | `TEXT` | Não determinável (view) | Caminho do `execution.md` canônico, quando disponível. |
+
+### `operations_monthly`
+
+- **Tipo:** View
+- **Finalidade:** Resumo mensal completo da área Operação, derivado das fontes canônicas.
+- **Grão/chave:** Uma linha por mês.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month ou year. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave YYYY-MM-DD, YYYY-MM ou YYYY conforme o grão. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil de São Paulo incluído no período. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil de São Paulo incluído no período. |
+| `prd_count` | `INTEGER` | Não determinável (view) | PRDs canônicos criados no período. |
+| `spec_count` | `INTEGER` | Não determinável (view) | SPECs canônicas criadas no período. |
+| `task_count` | `INTEGER` | Não determinável (view) | Tasks canônicas criadas no período. |
+| `validation_count` | `INTEGER` | Não determinável (view) | Validações canônicas registradas no período. |
+| `evidence_count` | `INTEGER` | Não determinável (view) | Evidências canônicas registradas no período. |
+| `total_run_count` | `INTEGER` | Não determinável (view) | Total de Runs raiz e Sub-Runs canônicos iniciados no período. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Atividades de agente com telemetria contabilizadas no período. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Chamadas LLM conhecidas no período; NULL quando indisponível. |
+| `operations_total_duration` | `REAL` | Não determinável (view) | União dos intervalos de execução no período, em milissegundos, sem dupla contagem de sobreposições. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos no período. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma do custo estimado em USD no período. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma do custo estimado em BRL no período. |
+
+### `operations_work_kanban`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_work_kanban; entrega identidade e métricas vitalícias próprias de cada cartão da aba Trabalho Kanban, sem repetir os totais globais do dashboard.
+- **Grão/chave:** Uma linha por cartão de trabalho.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_kind` | `derivada (sem afinidade declarada)` | Não determinável (view) | Tipo da entidade unificada: task, spec ou prd. |
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de atividades canônicas ligadas à entidade. |
+| `llm_call_count` | `INTEGER` | Não determinável (view) | Soma das chamadas LLM conhecidas da entidade; NULL quando não observada. |
+| `total_duration` | `REAL` | Não determinável (view) | União dos intervalos canônicos com tokens da entidade, em milissegundos; sobreposições entre raiz e subagentes contam uma vez. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma dos tokens conhecidos das atividades ligadas à entidade. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma do custo estimado em USD das atividades ligadas à entidade. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma do custo estimado em BRL das atividades ligadas à entidade. |
+
+### `operations_work_list`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_operations_work_list; Lista unificada de Tasks, SPECs e PRDs para a aba Trabalho Lista.
+- **Grão/chave:** Uma linha por entidade de trabalho.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_kind` | `derivada (sem afinidade declarada)` | Não determinável (view) | Tipo da entidade unificada: task, spec ou prd. |
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `prd_summary_daily`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_prd_summary_daily; Contagem diária de PRDs.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `prd_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de PRDs canônicos contabilizados no período. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `spec_summary_daily`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_spec_summary_daily; Contagem diária de SPECs.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `spec_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de SPECs canônicas contabilizadas no período. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `task_risk_daily`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_task_risk_daily; Distribuição diária de Tasks por classificação de risco.
+- **Grão/chave:** Uma linha por dia e risco.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `task_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de Tasks canônicas contabilizadas no período. |
+
+### `task_status_daily`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_task_status_daily; Distribuição diária de Tasks por estado canônico.
+- **Grão/chave:** Uma linha por dia e status.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `task_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de Tasks canônicas contabilizadas no período. |
+
+### `task_summary_daily`
+
+- **Tipo:** View
+- **Finalidade:** Alias público de vw_task_summary_daily; Contagem diária de Tasks.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `task_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de Tasks canônicas contabilizadas no período. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_agent_invocations`
+
+- **Tipo:** View
+- **Finalidade:** Detalhe de invocações com provedor e modelo consolidados; usa mixed quando há mais de um valor conhecido.
+- **Grão/chave:** Uma linha por agent_invocation_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador global da invocação de agente à qual a linha pertence. |
+| `summary_hash` | `TEXT` | Não determinável (view) | Hash do resumo canônico usado para detectar alterações e evitar reprojeções desnecessárias. |
+| `root_agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador da invocação raiz da árvore à qual a linha pertence. |
+| `parent_agent_invocation_id` | `TEXT` | Não determinável (view) | Identificador da invocação pai; NULL identifica uma invocação raiz. |
+| `execution_id` | `TEXT` | Não determinável (view) | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `task_id` | `TEXT` | Não determinável (view) | Identificador da Task ZAIP associada à linha, quando houver. |
+| `spec_id` | `TEXT` | Não determinável (view) | Identificador da SPEC ZAIP associada à linha, quando houver. |
+| `prd_id` | `TEXT` | Não determinável (view) | Identificador do PRD ZAIP associado à linha, quando houver. |
+| `change_id` | `TEXT` | Não determinável (view) | Identificador da Change ZAIP associada à linha, quando houver. |
+| `conversation_id` | `TEXT` | Não determinável (view) | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `run_id` | `TEXT` | Não determinável (view) | Identificador físico RUN-* que originou a invocação. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_kind` | `TEXT` | Não determinável (view) | Tipo da invocação: orquestradora ou delegada, conforme o registro canônico. |
+| `delegation_depth` | `INTEGER` | Não determinável (view) | Profundidade da invocação na árvore de delegação; zero representa a raiz. |
+| `zaip_agent` | `TEXT` | Não determinável (view) | Identidade catalogada do agente ZAIP responsável pela invocação. |
+| `phase` | `TEXT` | Não determinável (view) | Fase ZAIP em que a invocação ocorreu. |
+| `purpose` | `TEXT` | Não determinável (view) | Propósito operacional da invocação, como orquestração, execução ou finalização. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `duration_ms` | `REAL` | Não determinável (view) | Duração conhecida da invocação em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `REAL` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `REAL` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `cost_method` | `TEXT` | Não determinável (view) | Método usado para obter o custo estimado, permitindo interpretar sua proveniência. |
+| `pricing_model` | `TEXT` | Não determinável (view) | Modelo de precificação usado na estimativa de custo. |
+| `pricing_source` | `TEXT` | Não determinável (view) | Fonte da tabela ou regra de preços usada na estimativa. |
+| `fx_rate` | `REAL` | Não determinável (view) | Taxa de câmbio USD para BRL aplicada ao cálculo do custo estimado. |
+| `service_tier` | `TEXT` | Não determinável (view) | Tier de serviço do provedor associado à chamada, quando conhecido. |
+| `reasoning_effort` | `TEXT` | Não determinável (view) | Nível de esforço de raciocínio configurado ou observado para a chamada. |
+| `source_event_count` | `INTEGER` | Não determinável (view) | Quantidade de eventos canônicos consolidados para formar a invocação. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `provider` | `derivada (sem afinidade declarada)` | Não determinável (view) | Provedor LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `model` | `derivada (sem afinidade declarada)` | Não determinável (view) | Modelo LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+
+### `cost_annual`
+
+- **Tipo:** View
+- **Finalidade:** Métricas anuais de duração, tokens e custos estimados, com início e fim do período.
+- **Grão/chave:** Uma linha por ano.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_conversations`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações agregados por Conversation.
+- **Grão/chave:** Uma linha por conversation_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `conversation_id` | `TEXT` | Não determinável (view) | Identificador da conversa ZAIP associada à linha, quando houver. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_daily`
+
+- **Tipo:** View
+- **Finalidade:** Métricas diárias de duração, tokens e custos estimados, com início e fim do período.
+- **Grão/chave:** Uma linha por dia.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_executions`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e quantidade de invocações agregados por Execution.
+- **Grão/chave:** Uma linha por execution_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `execution_id` | `TEXT` | Não determinável (view) | Identificador da Execution ZAIP associada à linha, quando houver. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_group_daily`
+
+- **Tipo:** View
+- **Finalidade:** Projeção do agregado dimensional diário do Monitor de Custos.
+- **Grão/chave:** Uma linha por dia, tipo de grupo e valor.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `day` | `TEXT` | Não determinável (view) | Dia civil da projeção no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `group_kind` | `TEXT` | Não determinável (view) | Dimensão usada no agrupamento diário, como provedor, modelo ou agente. |
+| `group_value` | `TEXT` | Não determinável (view) | Valor concreto da dimensão indicada por group_kind; pode ser NULL quando não conhecido. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_input_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de entrada conhecidos no grão da linha. |
+| `total_cached_input_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de entrada em cache conhecidos no grão da linha. |
+| `total_output_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de saída conhecidos no grão da linha. |
+| `total_reasoning_tokens` | `REAL` | Não determinável (view) | Soma dos tokens de raciocínio conhecidos no grão da linha. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `cost_models`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações distintas agregados por modelo conhecido.
+- **Grão/chave:** Uma linha por modelo LLM.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `model` | `TEXT` | Não determinável (view) | Modelo LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_monthly`
+
+- **Tipo:** View
+- **Finalidade:** Métricas mensais de duração, tokens e custos estimados, com início e fim do período.
+- **Grão/chave:** Uma linha por mês.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_overview`
+
+- **Tipo:** View
+- **Finalidade:** Métricas do Monitor de Custos para todos os grãos temporais.
+- **Grão/chave:** Uma linha por período.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `period_kind` | `TEXT` | Não determinável (view) | Grão temporal do agregado: day, month, year ou all. |
+| `period_key` | `TEXT` | Não determinável (view) | Chave do período no grão indicado por period_kind, por exemplo dia, mês, ano ou all. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `cost_monitor_total_duration` | `REAL` | Não determinável (view) | Duração total usada pelo Monitor de Custos no período, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+| `start_day` | `TEXT` | Não determinável (view) | Primeiro dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `end_day` | `TEXT` | Não determinável (view) | Último dia civil incluído no período agregado, no formato YYYY-MM-DD. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+
+### `cost_prds`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações agregados por PRD.
+- **Grão/chave:** Uma linha por prd_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `prd_id` | `TEXT` | Não determinável (view) | Identificador do PRD ZAIP associado à linha, quando houver. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_providers`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações distintas agregados por provedor conhecido.
+- **Grão/chave:** Uma linha por provedor LLM.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `provider` | `TEXT` | Não determinável (view) | Provedor LLM conhecido atribuído ao segmento de uso ou ao agrupamento. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_specs`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações agregados por SPEC.
+- **Grão/chave:** Uma linha por spec_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `spec_id` | `TEXT` | Não determinável (view) | Identificador da SPEC ZAIP associada à linha, quando houver. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_tasks`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações agregados por Task.
+- **Grão/chave:** Uma linha por task_id.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `task_id` | `TEXT` | Não determinável (view) | Identificador da Task ZAIP associada à linha, quando houver. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `cost_zaip_agents`
+
+- **Tipo:** View
+- **Finalidade:** Tokens, custos estimados e invocações agregados por identidade de agente.
+- **Grão/chave:** Uma linha por agente ZAIP.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `zaip_agent` | `TEXT` | Não determinável (view) | Identidade catalogada do agente ZAIP responsável pela invocação. |
+| `total_tokens` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `cost_usd` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em dólares atribuído à linha ou segmento. |
+| `cost_brl` | `derivada (sem afinidade declarada)` | Não determinável (view) | Custo estimado em reais atribuído à linha ou segmento. |
+| `invocation_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+
+### `entities`
+
+- **Tipo:** View
+- **Finalidade:** União normalizada de entidades de trabalho para consultas comuns.
+- **Grão/chave:** Uma linha por Task, SPEC ou PRD.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `entity_kind` | `derivada (sem afinidade declarada)` | Não determinável (view) | Tipo da entidade unificada: task, spec ou prd. |
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+
+### `first_fold_prd_summary`
+
+- **Tipo:** View
+- **Finalidade:** Resumo compacto de PRDs para a primeira dobra.
+- **Grão/chave:** Uma linha por PRD.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `first_fold_spec_summary`
+
+- **Tipo:** View
+- **Finalidade:** Resumo compacto de SPECs para a primeira dobra.
+- **Grão/chave:** Uma linha por SPEC.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `first_fold_task_summary`
+
+- **Tipo:** View
+- **Finalidade:** Resumo compacto de Tasks para a primeira dobra.
+- **Grão/chave:** Uma linha por Task.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `id` | `TEXT` | Não determinável (view) | Identificador único da entidade representada pela linha. |
+| `title` | `TEXT` | Não determinável (view) | Título legível da entidade ZAIP. |
+| `status` | `TEXT` | Não determinável (view) | Estado canônico persistido da entidade ou da invocação representada. |
+| `risk` | `TEXT` | Não determinável (view) | Classificação de risco ZAIP da entidade; pode ser NULL quando indisponível. |
+| `occurred_at` | `TEXT` | Não determinável (view) | Instante canônico de ocorrência da entidade ou invocação, em formato ISO. |
+| `occurred_day_sp` | `TEXT` | Não determinável (view) | Dia civil derivado de occurred_at no fuso de São Paulo, no formato YYYY-MM-DD. |
+| `invocation_count` | `INTEGER` | Não determinável (view) | Quantidade de invocações distintas contabilizadas no grão da linha. |
+| `llm_call_count` | `derivada (sem afinidade declarada)` | Não determinável (view) | Soma de chamadas LLM conhecidas no grão da linha; NULL quando nenhuma invocação do grupo informa essa contagem. |
+| `total_duration` | `REAL` | Não determinável (view) | Soma das durações conhecidas no grão da linha, em milissegundos. |
+| `total_tokens` | `REAL` | Não determinável (view) | Soma de tokens conhecidos no grão da linha. |
+| `total_cost_usd` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em dólares no grão da linha. |
+| `total_cost_brl` | `REAL` | Não determinável (view) | Soma dos custos estimados conhecidos em reais no grão da linha. |
+
+### `agent_runs`
+
+View de negócio sobre `zaip_aios_activities`. Uma linha pela versão vigente de cada `agent_run_id`, com as métricas próprias do agente e suas relações de atividade. Uma versão que foi substituída permanece somente na fato, ligada por `version_activity_id`, e é excluída desta view para não duplicar totais. Use esta view para detalhes de agentes, custos e modelos.
+
+### `root_runs`
+
+Recorte de `agent_runs` em que `agent_run_role = root`. Uma raiz identifica a atividade coordenadora; `root_agent_run_id` é igual ao `agent_run_id` e `parent_agent_run_id` é `NULL`.
+
+### `sub_runs`
+
+Recorte de `agent_runs` em que `agent_run_role = subagent`. Cada linha representa um agente delegado e preserva `root_agent_run_id` e `parent_agent_run_id` para reconstruir a árvore.
+
+### `attributed_token_active_facts`
+
+View técnica no grão atividade × dia civil de São Paulo, reconstruída de payloads `duration_allocation`. Cada intervalo observado de atividade com tokens positivos é dividido nas fronteiras de início, fim e meia-noite; trechos simultâneos são rateados igualmente entre as atividades ativas. `attributed_token_active_ms` é a única medida aditiva de Tempo consumida pelas views.
+
+| Coluna | Tipo/afinidade | Nulabilidade | Explicação |
+|---|---|---|---|
+| `activity_row_id` | `TEXT` | Não nulo | Atividade canônica proprietária da fração temporal. |
+| `occurred_day_sp` | `TEXT` | Não nulo | Dia civil de São Paulo ao qual o segmento foi atribuído. |
+| `attributed_token_active_ms` | `REAL` | Não nulo | Milissegundos de relógio atribuídos após o rateio de concorrência. |
+
+### `attributed_token_active`
+
+View da fato temporal enriquecida com as dimensões da atividade canônica. Preserva o grão atividade × dia e é a origem direta dos agrupamentos temporais por Run, Execution, Task, SPEC, PRD, agente, período e total global.