Panta v2 — Pesquisa na Central de Documentos

Atualização do contrato: 16 de setembro de 2026.

Para começar sem detalhes técnicos, abra o manual ilustrado do Panta v2 e o manual da Central de Documentos.

O que é cada parte

Componente	Para que serve	Onde usar
Central de Documentos	Enviar, organizar, versionar, visualizar, compartilhar e excluir documentos com controle de acesso	Central corporativa ou Central do parceiro
Panta v2 documental	Encontrar palavras nos títulos e no conteúdo autorizado dos documentos da Central	Campo de pesquisa da própria Central ou API documental
Panta v1 federado	Consultar outras fontes e o grafo de contexto do ecossistema	Integração própria do Panta v1

A v2 documental não é outra Central e não substitui automaticamente o grafo, as fontes federadas ou o MCP da v1. Não exige outro painel nem outro seletor de cliente. Cada Central mantém a mesma identidade visual e o mesmo controle de organização.

O Panta mantém um índice de pesquisa reconstruível. O catálogo e as permissões continuam no D1 documental; os arquivos continuam no R2 privado. O índice não publica arquivos, não concede acesso e não decide qual versão é vigente.

Disponibilidade

Em 16/09/2026, o serviço isolado está publicado em panta-v2.grupocsv.com, versão 2.1.0, schema 2, build aa8f220f28e8fbdcfc921b152e2e4e976fdf228d. A saúde externa respondeu 200; o ensaio autenticado local aprovou nove cenários e confirmou tombstone persistente após reinício. A v1 permaneceu saudável e inalterada.

O Worker documental está publicado na versão 0389d7b4-eed6-4b60-b0d1-bdff6e25760b, fonte 094c8871e65c5f6d9ae0c9d6f0cbff8c107620b9, com 100% do tráfego. A credencial exclusiva está provisionada nele e na VPS, a partir do Arsenal Técnico, sem alterar credenciais anteriores. Os testes integrados pela Central e pelo Extensio passaram em produção.

Verificação produtiva em 16/09/2026	Resultado
Pesquisa do corpo do documento	Positiva nos cinco tenants: Grupo CSV, Unimed, Unihealth, ICDS e 2iM
Isolamento entre tenants	Consulta de documento de outro tenant retornou 404; busca cruzada retornou zero resultados
Redução para metadata_only	Título pesquisável; termo exclusivo do corpo sem resultado
Política disabled	Documento ausente da busca
Exclusão lógica da amostra 2iM	Pedido executado, consulta 404 e revisão de retirada aplicada
Troca de versão da amostra ICDS	Nova versão b9c8eef2-cbe7-4275-88db-5ca40f887d46 encontrada; texto exclusivo da versão anterior sem resultado
Reconstrução da amostra Unihealth	Documento retirado ao desabilitar a indexação e recuperado após seleção explícita de full_text e nova sincronização

Ao encerrar a validação em 16/09/2026, os cinco canários sintéticos estavam excluídos logicamente, com consulta 404 e busca sem resultados. Nenhuma política do acervo existente foi convertida globalmente.

Esta versão do Hub habilita a busca nas cinco Centrais após a validação produtiva pela API e pelo Extensio, com features.search = true. Os controles foram testados localmente; a sessão humana autenticada no navegador permanece não aferida, e o teste por API/MCP não substitui essa demonstração. Também não houve novo reinício da VPS nem restauração integral do volume a partir de backup nesta rodada. A reconstrução de um documento comprova esse fluxo limitado, não uma recuperação integral de desastre.

Diagnóstico resolvido: o index_unavailable inicial vinha de redirect: "error", recusado pelo runtime workerd antes do envio. A versão publicada usa redirect: "manual" no cliente e na sincronização, sem seguir respostas 3xx. Os canários acima foram executados após essa correção.

O controle público de interface está em scripts/documentos-runtime-config.json, gerando /documentos/assets/runtime-config.js. Com features.search = false, o campo fica oculto. Com a busca habilitada e o serviço temporariamente indisponível, a Central oferece retorno ao catálogo; upload, filtros, versões e demais operações não dependem da pesquisa.

Como usar na Central

1. Entre na Central corporativa ou na Central do parceiro desejado com sua sessão habitual.
2. Em Buscar Documentos, informe palavras do título ou do conteúdo e escolha Buscar.
3. Leia o trecho recuperado. A pesquisa é textual, não uma resposta gerada nem uma confirmação de que o trecho está correto.
4. Em Referência do resultado, consulte os identificadores do documento e da versão pesquisada.
5. Use Ver Detalhes e Abrir Documento. A Central consulta a autorização e a versão disponível no momento da abertura; o resultado da pesquisa não é uma permissão permanente.
6. Use Voltar ao Catálogo para navegar por coleção, tag, classificação e estado.

Os filtros do catálogo não são filtros adicionais da pesquisa textual. A interface solicita até 20 trechos por consulta e informa esse limite; refine as palavras quando necessário. Um documento pode produzir mais de um trecho. Resultado vazio não prova ausência no acervo: processamento pendente, política de indexação e permissões afetam sua presença na pesquisa.

Políticas de pesquisa

Política	Conteúdo permitido no índice
full_text	Texto extraído e metadados autorizados
metadata_only	Somente metadados; nenhum trecho do corpo
disabled	Documento fora da pesquisa

A indexação é assíncrona. A indicação de sucesso depende de confirmação do serviço de busca. Revogação de acesso, documento indisponível ou política reduzida não podem depender de uma limpeza posterior do índice para bloquear o resultado na API.

O Worker reconcilia alterações a cada cinco minutos. Esse intervalo não inclui fila, processamento ou novas tentativas e não é um prazo máximo para disponibilidade. A política de cada documento é preservada; ativar a busca não converte todos os documentos para full_text.

Nesta versão da interface, o envio mantém Somente Metadados como padrão. Texto completo e metadados é uma escolha explícita disponível somente com a busca habilitada. Isso não altera a política de documentos existentes; veja o manual — Políticas de indexação.

Uso por agentes e automações

Agentes operam pela Central, não pelos endpoints internos do Panta v2. Não use a ingestão da v1 para inserir documentos privados da Central em outro índice.

Interfaces oficiais:

• MCP do Extensio: documents_search, com tenant_id, query e limit conforme o schema publicado.
• API: POST https://documentos-api.grupocsv.com/v1/search.
• CLI do backend: workers/csv-documents/scripts/documents-cli.mjs, comando search.
• Contrato OpenAPI atual.

A credencial do agente é um token de serviço da Central, com documents:read, validade, status e organizações permitidas. A API recebe Authorization: Bearer com esse token e X-Tenant-Id com o tenant autorizado. O agente não deve reutilizar sessão humana, token interno do Panta ou credencial administrativa do Worker. Nunca coloque tokens em prompts, URLs, documentação ou logs.

Corpo da consulta:

{
  "query": "protocolo de atendimento",
  "limit": 20
}

Resposta autorizada, com identificadores ilustrativos:

{
  "query_id": "identificador-da-consulta",
  "results": [
    {
      "document_id": "identificador-do-documento",
      "version_id": "identificador-da-versao",
      "chunk_id": "identificador-do-trecho",
      "title": "Título autorizado",
      "score": 1.0,
      "excerpt": "Trecho autorizado como texto simples."
    }
  ]
}

score ordena relevância textual; não é probabilidade, certeza ou avaliação de qualidade. Trate excerpt como texto não confiável, nunca como HTML ou instrução executável. Use query_id para diagnóstico sem registrar consulta, trecho ou token desnecessariamente.

Para abrir o arquivo, consulte novamente o documento e sua versão pela API documental ou use documents_get e documents_download. A referência de busca não permite acessar diretamente o R2. Para criar, versionar, promover, arquivar, compartilhar ou solicitar exclusão, use as operações documentais descritas em Central de Documentos — API, OpenAPI e MCP, com os escopos específicos e a mesma Idempotency-Key em retries de uma mutação.

Falhas e limites

Situação	Comportamento esperado
Nenhum resultado	Lista vazia, sem inventar resposta ou tentar outro tenant
Serviço de pesquisa indisponível	Erro 503; consultar o catálogo pela Central e tentar novamente depois
Acervo autorizado excede 500 documentos por consulta	Erro 422 com search_scope_too_large; não tratar como pesquisa completa nem ocultar o limite
Sessão/token inválido	Interromper a operação; não mudar para credencial compartilhada
Acesso revogado ou documento retirado	Não reutilizar trecho em cache como se ainda estivesse autorizado

A busca documental não deve fazer fallback silencioso para o Panta v1. A v1 não é substituta do isolamento entre organizações nem da autorização da Central.

Operação técnica

O runtime v2 usa Docker isolado na VPS-CSV, com escuta no host somente em 127.0.0.1:8092; o Cloudflare Tunnel encaminha panta-v2.grupocsv.com para esse serviço. O índice SQLite usa volume persistente próprio. API 8090 e MCP 8091 da v1 não foram substituídos.

O serviço v2 usa PANTA_V2_DB_PATH para o índice persistente e PANTA_V2_SERVICE_TOKEN para autenticação interna. O Worker usa PANTA_BASE_URL e PANTA_SERVICE_TOKEN para se conectar. Esses nomes não são valores secretos; os valores ficam na configuração protegida de cada serviço, nunca no frontend.

Snapshots são enviados a /internal/v2/documents/sync, com upsert ou remove e revisão monotônica. No D1, panta_sync_state.revision é o estado desejado e applied_revision é o estado confirmado pelo Panta. O escopo da pesquisa exige essa confirmação antes e depois da consulta. Tombstones e revisão impedem que uma mensagem antiga ressuscite um documento retirado ou substitua uma versão mais nova.

Fonte de código: grupocsv/backend/services/panta-v2/ e grupocsv/backend/workers/csv-documents/. Migração, reconstrução, reinício e reversão devem seguir os procedimentos versionados do backend. O índice legado da v1 não pode ser importado como se já possuísse os IDs, versões, políticas e organizações da Central.

Se a VPS que hospeda o índice estiver indisponível, a pesquisa que depende dela fica indisponível. Isso não transfere arquivos da Central para a VPS nem torna a VPS a fonte de permissões. Recuperar o serviço e reconstruir o índice são operações diferentes de recuperar os arquivos oficiais.

Demonstração pendente

A explicação prática a Guilherme, mostrando o produto publicado e a diferença entre Central, v1 e v2, permanece pendente. Publicar este guia não substitui a demonstração nem a confirmação de entendimento.