Adaptadores

Os adaptadores são a forma como o ContractForge se torna nativo em cada plataforma sem colocar o código da plataforma no núcleo.

As principais respostas: o que significa o contrato?
O adaptador responde: esta plataforma pode preservar esse significado e como deve funcionar?

Divisão de responsabilidades

Camada	Possui	Não possui
Core	Vocabulário contratual, normalização semântica, correspondência de capacidades, planos abstratos e conceitos de evidência.	Spark, Databricks SDK, boto3, Azure SDK, Fabric SDK, clientes Snowflake ou execução em runtime.
Adaptador	Capacidades da plataforma, renderização nativa, execução opcional, integração com SDKs, resolução de credenciais e valores de evidência específicos da plataforma.	Alterar o significado do contrato ou rebaixar silenciosamente a semântica.

Status de planejamento

Status	Comportamento do adaptador
SUPPORTED	Renderize ou execute normalmente.
SUPPORTED_WITH_WARNINGS	Renderize ou execute com avisos explícitos no resultado do planejamento e revise o artefato.
REVIEW_REQUIRED	Produza diagnósticos e artefatos de revisão opcionais, mas não finja que o mapeamento é totalmente equivalente.
UNSUPPORTED	Retorne bloqueadores e não gere artefatos executáveis ​​para comportamento inseguro.

Adaptadores atuais

Adaptador	Superfície de implementação nativa
Databricks	Delta, Unity Catalog, Auto Loader, Lakeflow, Databricks SQL, Asset Bundles, Jobs e evidências apoiadas por Delta.
AWS	Glue Spark, Iceberg, Catálogo Glue, Lake Formation, publicação de artefato S3, definições de trabalho Glue, Terraform/CloudFormation e evidências apoiadas por Iceberg.
Fabric	Notebooks Lakehouse, OneLake, tabelas Lakehouse, shortcuts, deployment pipelines, APIs de governança Fabric e evidências Delta.
Snowflake	SQL, warehouses, tasks, streams, políticas de mascaramento, políticas de acesso a linhas e tabelas de auditoria.
GCP	BigQuery, jobs de carga GCS, orquestração Workflows, qualidade/linhagem/aspectos Dataplex, Secret Manager e evidências BigQuery.

Databricks é a implementação de referência. AWS, Snowflake, Fabric e GCP agora possuem superfícies suportadas estáveis para seus escopos documentados, com validação real entre adaptadores e limites explícitos de revisão. Adaptadores futuros devem provar paridade por meio de declarações de capacidade, testes e documentação.

Para orientação lado a lado, veja Testar contratos entre adaptadores. A página mostra os mesmos contratos medalhão GeoJSON reutilizados em Databricks, AWS, Snowflake, Fabric e GCP, com diferenças nativas mantidas na fronteira da plataforma.

O que os adaptadores devem preservar

Os adaptadores devem primeiro preservar a semântica do ContractForge e depois escolher a implementação nativa.

Exemplos:

• upsert exige semântica de merge/upsert.
• scd2 requer semântica de histórico, datação eficaz e comportamento da linha atual.
• filtros de linha e máscaras de coluna exigem primitivas de governança nativas ou um mapeamento explícito que requer revisão.
• a quarentena deve manter o sucesso/falha da execução separados do status de qualidade.
• as evidências devem registrar execuções, erros, qualidade, quarentena, alterações de esquema, linhagem, metadados de origem, ações de governança e sinais de custo, quando disponíveis.

Empacotamento

Cada adaptador é publicado de forma independente:

contractforge-core
contractforge-databricks
contractforge-aws
contractforge-fabric
contractforge-gcp
contractforge-snowflake

A direção da dependência é única:

adapter -> contractforge-core
contractforge-core -> no adapter dependency

Isso permite que as equipes instalem apenas os adaptadores necessários e que cada adaptador se mova no ritmo do tempo de execução da plataforma.

Entrega de pacote em runtime

Todos os adaptadores são distribuições Python, mas a entrega no runtime pertence ao adaptador:

Adaptador	Instalação do pacote	Entrega em runtime
Databricks	Pacote PyPI ou wheel enviado ao workspace.	Instalar pelo PyPI em jobs, clusters ou notebooks é o caminho normal; wheels anexadas são o fallback offline ou com versão fixada.
AWS	Pacote PyPI para ferramentas locais ou de CI.	Jobs Glue devem usar wheels no S3 para contractforge-core e contractforge-aws; PyPI público só é apropriado quando o job tem acesso externo controlado a pacotes.
Snowflake	Pacote PyPI para ferramentas locais ou de CI.	Artefatos SQL rodam nativamente; procedures Snowpark hospedadas usam imports ZIP preparados a partir das bibliotecas core e adapter.
Fabric	Pacote PyPI ou wheel anexada.	Notebooks Fabric precisam do core e do adaptador Fabric disponíveis no runtime do notebook; wheel anexada é o fallback offline ou com versão fixada.
GCP	Pacote PyPI para ferramentas locais, CI ou runners.	BigQuery e Workflows executam artefatos nativos; pacotes Python são necessários onde os comandos do adaptador renderizam, fazem deploy ou executam smokes desses artefatos.

Versionamento de deploy dos contratos

O versionamento de deploy dos contratos é um contrato compartilhado de plano de controle. O core é dono do schema de ctrl_deployment_versions e das regras de hash determinístico; cada adaptador é dono de onde essa tabela fica e de como ela é criada, atualizada e consultada em cada plataforma.

Cada comando de deploy cria um deployment_id único. Cada etapa de contrato ou artefato nativo implantado cria uma linha no ledger com:

• deployment_step_id: identificador determinístico da etapa dentro do deploy;
• deployment_hash: hash estável da linha de deploy, excluindo metadados mutáveis de resultado;
• contract_hash: hash estável do payload do contrato usado naquela etapa;
• environment_hash: hash estável do payload de ambiente resolvido;
• manifest_hash: hash estável do manifesto de deploy do adaptador.

Adaptador	Armazenamento do ledger de versões
Databricks	Tabela Delta no catálogo/schema de evidência configurado.
AWS	Tabela Iceberg registrada no Glue Catalog.
Snowflake	Tabela SQL no banco/schema de evidência configurado.
Fabric	Tabela Delta Lakehouse no schema de evidência configurado.
GCP	Tabela BigQuery no dataset de evidência configurado.

O ledger não muda a semântica de ingestão. Ele registra exatamente quais payloads de contrato e ambiente, quais artefatos de plataforma e quais versões de pacote runtime foram implantados, permitindo comparar deploys repetidos sem depender de nomes de arquivo ou timestamps da plataforma.

Formato de implantação AWS

AWS não analisa contratos YAML dentro do Glue. O adaptador interpreta contratos antes da implementação:

contract bundle
  -> render artifacts
  -> publish to environment.artifacts.uri
  -> materialize Glue job definition
  -> create or update Glue job

Usar:

contractforge-aws deploy contracts/orders.ingestion.yaml --environment environments/prod.aws.yaml

O ambiente possui localização do artefato S3, função Glue, dependências e armazém Iceberg. O contrato de ingestão permanece semântico.