A primeira versão do meu harness de IA já realizava trabalho útil. Ela registrava grafos, roteava chamadas de modelos, aplicava retentativas limitadas, validava resultados e emitia telemetria estruturada. Para uma aplicação, isso bastava para provar o modelo de execução.

Então tentei responder a uma pergunta mais difícil: como um segundo produto deveria usar a mesma base?

A resposta mais fácil seria copiar o código ou importar módulos de um checkout vizinho. As duas abordagens fariam uma demonstração funcionar. Nenhuma delas criaria uma infraestrutura em que produtos independentes pudessem confiar.

Uma plataforma reutilizável precisa saber exatamente qual release do harness está instalada, quais operações ela expõe, quais schemas essas operações aceitam, quais versões da infraestrutura são compatíveis e quais capacidades são necessárias. Ela também precisa rejeitar um pacote antes da execução quando essas declarações não correspondem à realidade.

O problema deixou de ser compartilhar arquivos Python e passou a ser projetar uma fronteira de pacote.

Reutilizar código-fonte cria acoplamento invisível

Importar outro repositório pelo caminho local parece eficiente porque elimina o trabalho de empacotamento. Também esconde quase todas as dependências que importam.

O consumidor pode depender de um arquivo sem commit, de uma organização específica de diretórios ou do branch que estiver aberto naquele momento. Dois ambientes podem importar códigos diferentes e ainda informar a mesma versão da aplicação. Uma mudança em um módulo interno pode quebrar consumidores que nunca deveriam saber que aquele módulo existia.

Copiar a implementação cria o problema oposto. A primeira cópia funciona, mas correções e mudanças de política começam a divergir imediatamente. Cada produto passa a manter sua própria versão de retentativas, adaptação de provedores, validação e telemetria.

Reutilizar arquivos não é o mesmo que reutilizar um contrato de plataforma.

Eu precisava que o harness se comportasse como uma dependência real. Um consumidor deveria instalar um artefato versionado, importar um SDK público pequeno e possuir apenas seus modelos de domínio, workflow e código de adaptação. A plataforma deveria validar esse pacote sem importar um checkout vizinho.

Empacote o contrato antes do comportamento

Mantive o SDK público deliberadamente pequeno. Ele exporta os tipos necessários para descrever um harness, associar pontos de entrada tipados e registrar uma definição instalada. Os módulos internos podem evoluir enquanto essa fronteira pública permanecer compatível.

Cada release do harness leva um manifesto estrito. O manifesto identifica o pacote e a release, declara o intervalo de versões compatíveis da infraestrutura e descreve cada ponto de entrada público. Cada ponto de entrada inclui as versões do grafo e do estado, além de schemas fechados de entrada e saída.

Uma definição simplificada se parece com esta:

Manifesto versionado do harness
manifest = HarnessManifest(
    harness_id="document-review",
    package_name="document-review-harness",
    version="1.0.0",
    infrastructure_requires=">=0.2.0,<0.3.0",
    required_capabilities=("model.step",),
    entry_points=(
        HarnessEntryPoint(
            entry_point_id="review",
            graph_id="document-review.review",
            graph_version="1.0.0",
            state_schema_version="1.0.0",
            input_schema=SchemaDescriptor.from_model(
                ReviewRequest,
                schema_id="document-review.request",
                version="1.0.0",
            ),
            output_schema=SchemaDescriptor.from_model(
                ReviewResult,
                schema_id="document-review.result",
                version="1.0.0",
            ),
        ),
    ),
)

O manifesto não contém caminho de importação, credencial nem expressão executável. Ele pode ser inspecionado com segurança como metadado. Explica o que uma release declara oferecer sem decidir qual objeto Python deve executar.

Essa distinção importa. Metadados podem ser lidos e comparados. Código executável precisa ser confiável.

O manifesto descreve; o binding executa

O pacote instalado também expõe uma factory que retorna uma definição. Essa definição associa cada ponto de entrada declarado ao modelo real de requisição, ao modelo de resultado e ao runner assíncrono.

O registro verifica a definição completa antes de publicar qualquer parte dela. A versão do pacote instalado precisa corresponder ao manifesto. A versão da infraestrutura deve estar dentro do intervalo declarado. As capacidades exigidas precisam estar disponíveis. Os nomes dos bindings devem corresponder exatamente aos pontos de entrada do manifesto. Os schemas reais do Pydantic devem ser iguais aos schemas registrados no manifesto.

Se uma verificação falhar, a release não entra no registro.

Isso evita um tipo comum de divergência: a documentação diz que uma operação aceita um formato, enquanto o código aceita outro. Também evita registro parcial, em que uma operação válida se torna visível antes de outra operação inválida provocar a falha do carregamento.

O registro armazena identidades exatas de release. Um chamador seleciona o ID e a versão do harness em vez de pedir qualquer implementação que por acaso seja a mais recente. Isso é essencial para reprodutibilidade e para continuar uma execução depois que uma release mais nova for instalada.

Descoberta não pode significar confiança automática

Usei os entry points padrão das distribuições Python para descoberta. Um pacote de harness pode anunciar sua factory por metadados normais do pacote, sem obrigar o host a manter um import fixo para cada domínio.

Mesmo assim, instalar um pacote não o ativa.

O host seleciona as factories instaladas em que confia na sua fronteira de composição. Apenas essas factories são carregadas, e a identidade da distribuição é verificada antes do registro. Uma requisição HTTP não pode fornecer um caminho de importação arbitrário nem pedir que o runtime carregue qualquer código instalado.

Essa é uma fronteira de segurança importante, embora não seja um sandbox. Uma factory Python pode executar Python. A revisão do pacote e a confiança do operador continuam sendo pré-requisitos.

A garantia útil é mais estreita e concreta: o runtime não confunde a possibilidade de descobrir um pacote com permissão para executá-lo.

Uma definição não é um deployment

Outra fonte de ambiguidade era a palavra instalado.

Uma release do harness pode existir como definição reutilizável e também estar instalada em vários workers. Esses são fatos diferentes.

A definição diz o que a versão 1.0.0 significa: seus pontos de entrada, schemas, requisitos e bindings executáveis. Um registro de deployment diz onde essa release foi observada: identidade do worker, versão do pacote instalado, versão da infraestrutura, capacidades, endpoint opcional e última observação de saúde.

Manter esses registros separados evita várias conclusões falsas:

Essa separação também prepara a infraestrutura para diferentes chamadores. Uma interface interativa, um cliente direto da API ou um scheduler externo poderão apontar para a mesma capacidade registrada sem assumir sua lógica de deployment.

Teste a fronteira de fora do repositório

Testes unitários dentro do pacote de infraestrutura poderiam provar que o registro funcionava com classes locais. Eles não poderiam provar que um time independente conseguiria criar um pacote usando apenas o SDK suportado.

Para isso, criei um pequeno harness sintético como um wheel separado. Ele possui seus schemas de requisição e resultado, publica sua própria factory e importa apenas o SDK público. Seu provedor controlado exercita o executor real de etapas de modelo, incluindo uma falha transitória seguida por uma retentativa limitada.

Também construí variantes inválidas do pacote. Uma exige uma versão incompatível da infraestrutura. Outra informa no manifesto uma versão diferente da distribuição instalada. O host precisa rejeitar ambas antes que possam executar.

Esse tipo de teste de conformidade é mais valioso do que um mock que apenas devolve uma resposta de sucesso fabricada. Ele verifica o mesmo caminho de instalação, descoberta, comparação de schemas, verificação de capacidades e execução usado por um consumidor real.

Isso também mantém os produtos de domínio fora da aceitação da infraestrutura. A plataforma pode provar seu contrato com pacotes neutros; cada domínio pode depois provar seu próprio comportamento contra a mesma fronteira pública.

Empacotamento reproduzível muda o valor da evidência

Transformar o código em pacote revelou problemas que os testes baseados no código-fonte escondiam.

A imagem de produção agora instala o wheel construído em vez de importar o diretório de trabalho. Os testes executam contra esse artefato instalado. Fixtures, rascunhos e ferramentas de build ficam fora do pacote de runtime. As dependências são fixadas com hashes, e novas montagens offline precisam produzir os mesmos bytes do wheel.

Os testes estritos de schema também encontraram um problema sutil de validação. Um campo destinado a aceitar uma versão inteira de schema ainda podia aceitar equivalentes booleanos ou decimais por causa das regras de igualdade do Python. Uma verificação explícita do tipo exato eliminou essa brecha.

Esses detalhes podem parecer pequenos, mas mudam a força da evidência. “Os testes passaram no meu checkout” é mais fraco do que “este artefato exato foi instalado em um runtime limpo, rejeitou consumidores incompatíveis e foi reproduzido a partir de entradas fixadas”.

O que essa fronteira ainda não promete

O empacotamento resolve identidade, compatibilidade, descoberta e invocação local tipada. Ele não transforma uma chamada de função local em uma execução governada.

A fronteira atual não autentica um chamador, cria uma execução durável, persiste estado, aplica permissões, reserva orçamentos compartilhados nem recupera trabalho depois da falha de um processo. Uma permissão declarada ainda é metadado até que uma camada de admissão a verifique e aplique. Um registro de deployment ainda é uma observação até que existam um worker e um protocolo de saúde.

Declarar esses limites faz parte da arquitetura. Se uma chamada local do SDK fosse apresentada como uma API de execução para produção, interfaces e schedulers futuros seriam construídos sobre garantias que não existem.

A fronteira de pacote cria um lugar estável para adicionar essas garantias. A autenticação pode admitir uma release e um ponto de entrada exatos. A execução durável pode fixar as mesmas versões de schema e grafo. Workers podem ativar pacotes selecionados. Uma API pública pode expor a capacidade sem revelar imports Python nem depender de uma sessão de interface interativa.

A reutilização começa quando a fronteira sobrevive à mudança

O resultado mais importante não é conseguir carregar um segundo wheel. É permitir que a plataforma e o domínio mudem de forma independente dentro de um contrato explícito.

A infraestrutura possui o registro, as verificações de compatibilidade, os mecanismos compartilhados de execução e o SDK suportado. Um pacote de domínio possui seus schemas, workflow e decisões de release. A configuração de deployment decide quais pacotes revisados se tornam ativos. No futuro, os chamadores usarão um único contrato de execução, sejam eles uma interface, uma integração de API ou um scheduler externo.

Essa é a diferença entre um harness funcional e uma infraestrutura de harness reutilizável. O grafo continua importante, mas o produto reutilizável é a fronteira ao redor dele: versionada, inspecionável, ativada de forma deliberada e testada pelo ponto de vista do consumidor.