Publicação e embalagem

Propósito

ContractForge Core, cada adaptador de plataforma e o complemento AI são publicados como distribuições Python separadas.

Este é um limite de empacotamento, não apenas uma preferência de código-fonte. A instalação do contractforge-core nunca deve instalar Databricks, AWS, Fabric, Snowflake, GCP ou outros pacotes de adaptadores de plataforma, a menos que o usuário instale explicitamente um.

Distribution Ownership

Distribution	Possui pacote	Possui scripts de console	Depends on
contractforge-core	contractforge_core	contractforge	Somente dependências de tempo de execução principais.
contractforge-databricks	contractforge_databricks	contractforge-databricks	contractforge-core mais dependências de tempo de execução opcionais do Databricks.
contractforge-aws	contractforge_aws	contractforge-aws	contractforge-core mais dependências de tempo de execução opcionais do AWS.
contractforge-fabric	contractforge_fabric	contractforge-fabric	contractforge-core mais dependências de tempo de execução opcionais do Fabric.
contractforge-snowflake	contractforge_snowflake	contractforge-snowflake	contractforge-core mais dependências de tempo de execução opcionais do Snowflake.
contractforge-gcp	contractforge_gcp	contractforge-gcp	contractforge-core mais dependências de tempo de execução opcionais do GCP.
contractforge-ai	contractforge_ai	contractforge-ai	contractforge-core mais extras opcionais de provedor e adaptador.

A direção da dependência é unilateral:

platform adapter wheel -> contractforge-core wheel
contractforge-core wheel -> no platform adapter wheel

O núcleo pode definir protocolos públicos, modelos semânticos, análise de contratos, modelos de capacidade, planejamento, modelos de evidências e comandos CLI genéricos. Não deve depender de um pacote adaptador para fornecer essas superfícies.

Regras da Roda Central

A roda contractforge-core deve incluir apenas:

• contractforge_core
• documentação principal e metadados necessários para publicação
• o script do console contractforge
• dependências neutras em plataforma

A roda central não deve incluir:

• contractforge_databricks
• pacotes de adaptadores como contractforge_aws, contractforge_fabric, contractforge_snowflake ou contractforge_gcp
• scripts do console do adaptador, como contractforge-databricks
• SDKs de plataforma ou clientes de tempo de execução
• Dependências do conector Spark, Databricks SDK, boto3, Azure SDK, Fabric SDK ou Snowflake

Regras da roda adaptadora

Cada roda adaptadora deve incluir apenas seu pacote de adaptadores e pontos de entrada de propriedade do adaptador.

Para contractforge-databricks, a distribuição do adaptador possui:

• contractforge_databricks
• o script do console contractforge-databricks
• Renderização específica de Databricks, SQL, auxiliares de tempo de execução, tabela de controle DDL, Lakeflow, Unity Catalog, Delta e lógica Asset Bundle
• an explicit dependency on a compatible contractforge-core version

O pacote do adaptador pode expor extras opcionais para integrações de tempo de execução. Por exemplo, o suporte Databricks Connect ou PySpark deve ser opcional, a menos que o adaptador publique intencionalmente um extra com muito tempo de execução.

Monorepo Layout

O repositório é organizado para que cada distribuição publicável tenha seu próprio manifesto de projeto:

pyproject.toml
src/
  contractforge_core/
adapters/
  databricks/
    pyproject.toml
    src/
      contractforge_databricks/
  aws/
    pyproject.toml
    src/
      contractforge_aws/
  fabric/
    pyproject.toml
    src/
      contractforge_fabric/
  snowflake/
    pyproject.toml
    src/
      contractforge_snowflake/
  gcp/
    pyproject.toml
    src/
      contractforge_gcp/
ai/
  pyproject.toml
  src/
    contractforge_ai/

A raiz pyproject.toml é o projeto contractforge-core. adapters/databricks/pyproject.toml é o projeto contractforge-databricks. adapters/aws/pyproject.toml é o projeto contractforge-aws. adapters/fabric/pyproject.toml é o projeto contractforge-fabric. adapters/snowflake/pyproject.toml é o projeto contractforge-snowflake. adapters/gcp/pyproject.toml é o projeto contractforge-gcp. ai/pyproject.toml é o projeto contractforge-ai.

Monorepo Development Rule

Uma verificação de desenvolvimento pode manter contractforge_core e um ou mais adaptadores no mesmo repositório enquanto a arquitetura está sendo construída.

A publicação ainda deve produzir rodas separadas. A colocation de origem não é permissão para publicar uma distribuição combinada.

Os testes podem importar ambos os pacotes do checkout local, mas os testes de empacotamento devem provar que o build principal tem como alvo apenas os pacotes contractforge_core.

Limite CLI

O núcleo contractforge CLI possui comandos de plataforma neutra:

• validar contratos
• redigir contratos divididos
• inspect semantic plans
• renderizar saída de revisão genérica
• mostrar informações públicas de esquema/especificação

O adaptador CLI possui comandos nativos do adaptador:

• renderizar artefatos de plataforma
• inspecionar os recursos do adaptador
• renderizar painéis ou pacotes do adaptador
• executar visualizações de governança específicas do adaptador
• executa auxiliares de tempo de execução de propriedade do adaptador quando explicitamente suportado

O CLI principal pode descobrir adaptadores instalados no futuro, mas não deve importar pacotes de adaptadores no momento da importação do módulo.

Versioning

As rodas principais e adaptadoras podem ter versões independentes.

Política recomendada:

1. As principais mudanças que alteram os modelos públicos ou a semântica do planejador incrementam a versão secundária principal até 1.0.
2. As rodas adaptadoras declaram uma gama de núcleos compatível.
3. As melhorias de artefato/tempo de execução somente do adaptador não exigem uma versão principal.
4. Um novo conceito semântico central não está completo até que especificações, testes, mapeamento de capacidade e comportamento do adaptador ou bloqueadores explícitos sejam atualizados.

Exemplo de dependência do adaptador:

dependencies = [
  "contractforge-core>=0.1,<0.2",
]

Build Verification

Before publishing contractforge-core, verify:

python -m build --wheel

A roda produzida deve conter contractforge_core e não deve conter contractforge_databricks.

Antes de publicar um adaptador, verifique se a roda do adaptador contém o pacote do adaptador, depende do contractforge-core e não vende ou copia o pacote principal.

Para Databricks:

cd adapters/databricks
python -m build --wheel

Para AWS:

cd adapters/aws
python -m build --wheel

Para Fabric:

cd adapters/fabric
python -m build --wheel

Para Snowflake:

cd adapters/snowflake
python -m build --wheel

Para GCP:

cd adapters/gcp
python -m build --wheel

Para IA:

cd ai
python -m build --wheel

A distribuição AI atualmente usa setuptools enquanto núcleo e adaptador distribuições usam hatchling. Isso é intencional para a primeira IA pública lançamento porque contractforge-ai envia modelos de prompt como dados de pacote e a configuração existente do setuptools já está coberta pela versão de lançamento. Não migre o back-end durante um lançamento, a menos que o conteúdo wheel e sdist seja revalidado.

Assets da GitHub Release

PyPI é o índice canônico de pacotes Python, mas GitHub Releases também devem carregar assets prontos para runtime em ambientes que não conseguem acessar o PyPI ou que exigem uma extensão específica de arquivo:

• .whl para instalação Python normal e dependências hospedadas em S3 ou no workspace;
• .tar.gz como distribuição fonte para rebuilds e auditoria;
• .zip como alias copiado do arquivo wheel para runtimes como procedures Python Snowflake, que aceitam imports ZIP em stage mas rejeitam imports .whl.

O alias ZIP deve conter os mesmos bytes da wheel. Ele é um formato de entrega em runtime, não um build diferente do pacote.

Critérios de aceitação

Uma versão é publicável somente quando:

• contractforge-core builds its own wheel.
• cada adaptador constrói sua própria roda.
• a roda principal não inclui módulos adaptadores ou scripts adaptadores.
• cada adaptador declara contractforge-core como uma dependência.
• o companheiro de IA declara contractforge-core como uma dependência.
• as dependências do adaptador nunca vazam para as dependências principais.
• os documentos descrevem a instalação e o uso para fluxos somente núcleo e núcleo mais adaptador.
• os assets do workflow de release incluem wheel, distribuição fonte e alias ZIP para entrega em runtime.