Criação de adaptador

Um adaptador é a camada de implementação da plataforma para ContractForge. Não mudar o que um contrato significa. Ele decide se a plataforma alvo pode preserva esse significado, renderiza artefatos nativos e, quando suportado, executa com evidências auditáveis.

Use o adaptador Databricks como estilo de referência. Usar AWS, Snowflake, Fabric e GCP como exemplos de superfícies estáveis ​​não-Databricks. Um novo adaptador não precisa copiar seus módulos internos, mas deve preservar o mesmo público limite do contrato.

Modelo mental

contract YAML
  -> core validation and semantic normalization
  -> adapter capability planning
  -> native artifact rendering
  -> optional publish/register/execute
  -> evidence and diagnostics

O núcleo possui vocabulário de contrato. O adaptador possui ligação nativa.

Camada	Possui	Não deve fazer
Essencial	Esquema de contrato, normalização, primitivas de planejamento, modelos de evidência neutra, taxonomia de origem e aliases de modo de gravação.	Importe SDKs da plataforma ou conheça as credenciais da plataforma.
Adaptador	Capacidades, nomenclatura nativa, execução de origem, gravações, governança, implantação, clientes de tempo de execução e evidências de plataforma.	Faça downgrade silenciosamente da semântica ou adicione significado de plataforma a campos de contrato portáteis.

Interface pública mínima

O formato do adaptador público é intencionalmente pequeno:

from contractforge_core.adapters import PlatformAdapter, RenderedArtifacts
from contractforge_core.capabilities import PlatformCapabilities
from contractforge_core.planner import ExecutionPlan, PlanningResult, plan_contract
from contractforge_core.semantic import SemanticContract


class MyPlatformAdapter:
    name = "my-platform"

    def capabilities(self) -> PlatformCapabilities:
        ...

    def plan(self, contract: SemanticContract) -> PlanningResult:
        return plan_contract(contract, self.capabilities())

    def render(self, plan: ExecutionPlan) -> RenderedArtifacts:
        ...

Pacotes de produção podem expor APIs de propriedade de adaptadores mais ricos, como deploy_project, execute_plan, apply_access_contract ou stabilization_report. Esses APIs ainda devem ser reduzidos a capacidades, planejamento, renderização, execução e evidência.

Ciclo de criação

Etapa	Saída	Sinal de aceitação
Declare capability	Conservative PlatformCapabilities.	A semântica não suportada e necessária para revisão é explícita.
Planejar contratos	PlanningResult com avisos e bloqueadores.	Os status principais são preservados: SUPPORTED, SUPPORTED_WITH_WARNINGS, REVIEW_REQUIRED, UNSUPPORTED.
Renderizar artefatos	SQL, scripts, definições de trabalho, manifestos ou revisão Markdown.	A renderização nunca implica a execução de planos inseguros.
Vincular tempo de execução	Clientes de plataforma, credenciais, armazéns, trabalhos ou clusters.	Os SDKs são importados lentamente ou injetados pelos chamadores.
Execute com segurança	runner de propriedade do adaptador.	As execuções são idempotentes onde prometidas e falham com diagnósticos úteis.
Persistir evidência	Registros consultáveis ​​de execução, qualidade, erro, esquema, linhagem, governança e custo.	As evidências são redigidas e podem provar o que aconteceu.
Documentar escopo	Guia do adaptador e matriz de capacidade.	Os usuários podem ver limites suportados, avisos, revisão e não suportados.

Superfícies necessárias

Superfície	Necessário para adaptador estável	Observações
Modelo de capacidade	Yes	Declare apenas a semântica que o adaptador pode preservar. Recursos nativos semelhantes não são suficientes.
Catálogo de suporte de origem	Yes	Publique suporte à família de origem, mapeamento nativo, status e notas de revisão.
Escrever mapeamento	Yes	Mapeie append, overwrite, upsert, hash_diff_upsert, historical e reconciliação de instantâneo explicitamente.
Política de esquema	Yes	Preservar strict, additive_only, comportamento permissivo e decisões de ampliação de tipo.
Execução de qualidade	Yes	Avalie ou processe verificações suportadas e persista evidências em nível de regra.
Mapeamento de governança	Dependente da plataforma	Mapeie anotações, operações e acesso onde existem controles nativos.
Armazenamento de evidências	Yes	Adaptadores estáveis ​​precisam de evidências consultáveis, não apenas de mensagens de log.
Execução em tempo de execução	Esperado	Adaptadores somente de renderização são úteis, mas não são adaptadores de tempo de execução maduros.
CLI/API integration	Esperado	Mantenha os comandos principais genéricos e os comandos do adaptador de propriedade da plataforma.

Regras de capacidade

As capacidades são um contrato com os usuários. Seja conservador.

Do:

• retorne SUPPORTED apenas para comportamento equivalente;
• retorne SUPPORTED_WITH_WARNINGS para advertências inquebráveis;
• retornar REVIEW_REQUIRED quando for necessária uma escolha de design de plataforma;
• retornar UNSUPPORTED quando a semântica não puder ser preservada;
• documentar por que cada limite existe.

Do not:

• trate o acréscimo como um substituto para upsert;
• trate a substituição como um substituto para a reconciliação de instantâneos;
• trate uma tabela de viagem no tempo como suporte completo a historical, a menos que a linha atual sinalizadores, janelas de validade e comportamento de chegada tardia são preservados;
• executar planos que exigem revisão por padrão;
• persistir segredos em metadados ou evidências.

Comportamento da fonte e do conector

Os adaptadores consomem a taxonomia de origem principal e a vinculam a leituras nativas.

Família de origem	Obrigação do adaptador
Catálogo/tabela/consulta	Resolva referências lógicas como source.ref e {{ table_ref:silver.orders }} para nomes de tabelas nativas.
Arquivos e armazenamento de objetos	Preserve opções de formato, manipulação de esquemas, credenciais e segurança de caminho.
Incremental files	Mapeie para um mecanismo de rastreamento de arquivos da plataforma ou seja necessária revisão de retorno.
JDBC	Lide com drivers, particionamento, credenciais e pushdown de predicados sem vazar segredos.
REST e HTTP	Use comportamento de busca validado e limitado ou renderize artefatos de revisão/nativos.
Bounded streams	Implemente a semântica de repetição de atualização, a menos que um contrato de streaming mais forte seja explicitamente documentado.
Passagem nativa	Mantenha a configuração do conector específico da plataforma atrás dos campos de propriedade do adaptador e revise os artefatos.

Os nomes dos conectores específicos da plataforma não devem se tornar uma entrada principal portátil. Se o adaptador suporta atalhos nativos, documente-os nas extensões do adaptador e warn on unknown extension keys.

Mapeamento de modo de gravação

Os contratos públicos usam aliases de modo de gravação. Nomes internos canônicos permanecem dentro a biblioteca.

Modo de contrato	O adaptador deve provar
append	As linhas são adicionadas sem reconciliação de destino.
overwrite	O escopo de destino declarado é substituído pela atomicidade apropriada à plataforma.
upsert	Chaves estáveis ​​atualizam o estado atual de forma determinística.
hash_diff_upsert	Row-hash comparison semantics are preserved.
historical	As linhas do histórico, o marcador da linha atual, as janelas de validade e o comportamento de chegada tardia são preservados.
snapshot_reconcile_soft_delete	A origem é concluída antes que as chaves ausentes sejam marcadas como inativas ou excluídas.
custom:<name>	A execução passa por um manipulador explícito registrado no adaptador.

Se o adaptador não puder preservar um modo, ele deverá bloquear ou exigir revisão. Deve não execute silenciosamente uma gravação mais fraca.

Contrato de provas

Os adaptadores estáveis ​​precisam de evidências que possam ser consultadas após uma execução. No mínimo, persista ou renderize estes conceitos:

Evidência	Minimum requirement
Runs	Status, origem, destino, modo, carimbos de data/hora, métricas e resumo de erros.
Qualidade	Resultado em nível de regra, gravidade, contagens com falha e referência de quarentena quando usado.
Errors	Mensagem de erro redigida, diagnóstico da plataforma e etapa com falha.
Mudanças de esquema	Desvio detectado, alterações aplicadas e decisão política.
State	Marcas d'água, bloqueios ou chaves de idempotência necessárias para a semântica suportada.
Lineage	Referências de origem e destino, operação e correlação de execução.
Governança	Anotações, concessões, políticas, máscaras e filtros de linha aplicados.
Cost	Sinal de custo nativo da plataforma, quando disponível.

As evidências devem ser redigidas antes da persistência. Se a atribuição de custos ou a governação a evidência não estiver disponível, documente a limitação em vez de forjá-la.

Governança e acesso

Os adaptadores devem mapear a governança do ContractForge para controles nativos quando equivalentes existem recursos de plataforma:

Conceito de contrato	Exemplos nativos
Descrições de tabelas e colunas	Catalog comments, metadata APIs, data catalog descriptions.
Tags, aliases e sensibilidade	Tags nativas, rótulos, classificações ou tags de política.
Grants	SQL grants, IAM, Lake Formation, role bindings.
Row filters	Políticas de acesso a linhas, filtros de dados ou políticas de segurança revisadas.
Column masks	Mascaramento de políticas, tags de política ou segurança em nível de coluna.
Política de deriva	Compare o estado declarado e o atual; exigem aprovação explícita para mudanças destrutivas.

Quando a herança nativa ou a semântica de aplicação diferem, retorne REVIEW_REQUIRED.

Tempo de execução e padrão de implantação

Mantenha a implantação separada do significado do contrato:

contract bundle
  -> render native artifacts
  -> publish artifacts when needed
  -> register/update platform job
  -> execute only when requested
  -> record evidence

Exemplos:

• Databricks renderiza e implanta Asset Bundles, trabalhos e evidências apoiadas por Delta.
• AWS publica artefatos no S3, registra trabalhos Glue e grava evidências Iceberg.
• Snowflake prepara código, executa SQL ou procedimentos hospedados e grava tabelas de auditoria.
• Fabric implanta notebooks gerados e grava evidências Lakehouse Delta.
• GCP renderiza artefatos BigQuery e Workflows e grava evidências BigQuery.

O contrato de ambiente possui dicas de tempo de execução, como warehouse, cluster, função, artefato URI, localização de dependência e localização de evidências. O contrato de ingestão continues to own dataset semantics.

Layout de pacote sugerido

Mantenha as preocupações da plataforma separadas:

contractforge_<platform>/
  adapter.py
  api.py
  environment.py
  capabilities/
  sources/
  execution/
  schema/
  quality/
  governance/
  evidence/
  runtime/
  rendering/
  diagnostics/
  tests/

Evite um renderizador grande que possua análise de origem, geração de SQL, execução, evidências e governança ao mesmo tempo. Torna-se difícil provar maturidade.

Testing matrix

Test group	Cobertura necessária
Limite central	Núcleo de importação de adaptadores; core nunca importa adaptador.
Planejamento de capacidade	Planos com suporte, aviso, revisão obrigatória e sem suporte.
Análise de contrato	Ingestão, anotações, operações, acesso e ambiente.
Sources	Cada família de origem declarada suportada, além de casos não suportados/revisados.
Writes	Cada modo de gravação declarado e nenhum substituto silencioso.
Esquema	Caminhos estritos, aditivos, permissivos, de ampliação de tipo e bloqueadores.
Qualidade	Aprovar, reprovar, avisar, abortar e colocar em quarentena.
Governança	Anotações, concessões, filtros, máscaras e política de desvio quando suportadas.
Evidência	Registros de execução, qualidade, erro, esquema, estado, linhagem e governança.
Tempo de execução	runners falsos primeiro; testes de smoke em plataforma real antes de reivindicações estáveis.
Redaction	Segredos, tokens, credenciais e URLs inseguros nunca aparecem em evidência.

Maturidade ponta a ponta significa que a mesma família de contratos pode transformar bronze em ouro usando apenas contratos e vinculações de ambiente documentadas, sem scripts de solução alternativa.

Maturity levels

Level	Significado
Somente renderização	Produz artefatos de revisão/nativos, mas não executa.
Runnable	Executa contratos simples com código de tempo de execução de propriedade do adaptador.
Validated	Possui testes reais de ponta a ponta para fontes representativas, gravações, qualidade e evidências.
Estável	Possui escopo documentado, evidências repetidas, tratamento de falhas, limites de governança e nenhum rebaixamento semântico silencioso.
Production-certified	Adiciona runbooks operacionais, atribuição de custos, revisão de segurança, política de suporte e garantias de atualização.

Estável não significa que todos os recursos da plataforma estejam implementados. Significa o superfície documentada é explícita, testada e honesta.

Lista de verificação de documentação

Todo adaptador estável deve publicar:

• seções de contrato apoiadas;
• suporte ao conector de origem;
• comportamento no modo de gravação;
• esquema e comportamento de qualidade;
• anotações, operações e mapeamento de acessos;
• mapeamento de evidências/tabelas de controle;
• pré-requisitos e credenciais de tempo de execução;
• fluxo de implantação;
• unsupported semantics;
• semântica necessária para revisão;
• evidências reais de ponta a ponta.

Anti-patterns

Evite estes:

• adicionar nomes de origem específicos da plataforma ao núcleo quando uma extensão do adaptador for suficiente;
• accepting unknown extension keys silently;
• executar planos que exigem revisão por padrão;
• fazer com que os artefatos de revisão gerados pareçam executáveis;
• importar SDKs da plataforma no momento da importação do pacote;
• tratar exemplos como prova de suporte sem tabelas e testes de evidências;
• documenting only happy paths;
• usando documentos do adaptador para ocultar diferenças semânticas.

Acceptance checklist

Um adaptador é maduro o suficiente para ser chamado de estável quando:

• as capacidades são conservadoras e documentadas;
• todo modo de gravação suportado possui testes e evidências de tempo de execução;
• o suporte de origem é legível por máquina ou claramente documentado;
• a semântica não suportada e com necessidade de revisão fica visível para os usuários;
• a evidência persiste em registros de execução, qualidade, erro, esquema e linhagem;
• secrets are redacted;
• a implantação não altera a semântica do contrato;
• os testes ponta a ponta usam contratos, não código de solução alternativa;
• os documentos mostram a reutilização de contratos compartilhados e diferenças de ligação nativa.

O contrato de implementação exaustivo está em Guia de criação de adaptadores.