Arquitetura e limites do pacote.
ContractForge é organizado em torno de um limite rígido: o núcleo descreve a intenção de ingestão e os adaptadores traduzem essa intenção em comportamento nativo da plataforma.
Layered flow
O núcleo pode planejar sem clientes Spark, Databricks, boto3, Azure SDK, Fabric SDK ou Snowflake. As bibliotecas de plataforma residem apenas em pacotes de adaptadores.
Responsabilidades principais
| Domain | O núcleo possui |
|---|---|
| Contratos | Modelos de ingestão, anotações, operações, acesso e ambiente. |
| Semantics | Objetos de contrato semântico imutáveis e validação portátil. |
| Capabilities | Declarações de capacidade, correspondência e status de planejamento. |
| Planejamento | Planos de execução abstratos, bloqueadores, avisos e marcadores de revisão. |
| Evidência | Conceitos de evidência neutra e campos obrigatórios para paridade operacional. |
| Diagnostics | Mensagens de portabilidade, erros de validação e expectativas de autoria do adaptador. |
O núcleo nunca deve conter ramificações como if platform == "databricks". Use declarações de capacidade e comportamento do adaptador.
Responsabilidades do adaptador
| Domain | Adaptador possui |
|---|---|
| Capabilities | O que a plataforma pode preservar, o que requer revisão e o que não tem suporte. |
| Rendering | SQL nativo, Python, YAML, definições de pipeline, arquivos de pacote ou relatórios de revisão. |
| Execução | Execução opcional em tempo de execução na plataforma de destino. |
| Preenchimento de evidências | Valores específicos da plataforma passados para a evidência principal API. |
| Aplicação de governança | Concessões nativas, filtros de linha, máscaras, tags, comentários e primitivas de política. |
| Dependências de tempo de execução | SDKs, Spark, clientes da plataforma, drivers e resolução de credenciais. |
Databricks é o adaptador de referência. Possui Delta, Unity Catalog, Auto Loader, Lakeflow, Databricks SQL, Asset Bundles, auxiliares de tempo de execução e extensões específicas do Databricks.
Repository layout
src/
contractforge_core/
contracts/
semantic/
capabilities/
planner/
evidence/
connectors/
adapters/base/
adapters/
databricks/
src/
contractforge_databricks/
docs/
specs/
adrs/
site/
docs/
src/
Publication stays split:
| Distribution | Contains | Depends on |
|---|---|---|
contractforge-core | contractforge_core | Nenhum adaptador de plataforma. |
contractforge-databricks | contractforge_databricks | contractforge-core. |
| Futuras rodas adaptadoras | Um pacote de adaptador cada | contractforge-core. |
Public APIs
O núcleo estável API é usado por autores de ferramentas, CI e adaptadores:
| Area | Exemplos de pontos de entrada |
|---|---|
| Validação de contrato | validate_contract, load_contract_bundle, compose_contract_sections |
| Semantic normalization | semantic_contract_from_mapping |
| Planejamento | plan_contract, PlanningResult, PlanningStatus |
| Capabilities | PlatformCapabilities, NativeCapability |
| Protocolo adaptador | PlatformAdapter, RenderedArtifacts |
O adaptador Databricks expõe a execução e renderização específicas do Databricks:
| Area | Exemplos de pontos de entrada |
|---|---|
| Planejamento/renderização | plan_databricks_contract, render_databricks_contract |
| Execução em tempo de execução | ingest_databricks_bundle, ingest_databricks_contract |
| Environment | DatabricksEnvironment, DatabricksIngestOptions |
Regras de projeto
- Mantenha os SDKs da plataforma fora do
contractforge_core. - Prefer immutable semantic objects in planner-facing code.
- Make unsupported semantics explicit.
- Nunca faça downgrade silenciosamente do modo de gravação, do comportamento de governança ou dos requisitos de evidência.
- Adicione documentos, testes, mapeamento de recursos e comportamento do adaptador para cada novo conceito semântico.
- Divida os módulos por limites de domínio estáveis, não por conveniência.
Extension path
Para adicionar um novo adaptador de plataforma:
- Implement a capability declaration.
- Reutilize o planejamento principal, a menos que o adaptador precise de diagnósticos mais rigorosos.
- Renderize artefatos nativos a partir do plano abstrato.
- Preencha o modelo de evidência neutra com valores específicos da plataforma.
- Documento suportado, aviso, comportamento necessário para revisão e não suportado.
- Publique o adaptador como sua própria roda.
Consulte Criação de adaptador para obter o contrato completo.