Visão geral do ContractForge
ContractForge é uma plataforma de ingestão orientada por contratos para múltiplos runtimes. Ele define a intenção de ingestão em um núcleo semântico neutro, avalia essa intenção contra as capacidades de cada adaptador e permite que cada plataforma renderize ou execute artefatos nativos.
contractforge-core, contractforge-databricks, contractforge-aws, contractforge-snowflake, contractforge-fabric e contractforge-gcp são limites de entrega: o núcleo possui a semântica do contrato, enquanto os adaptadores possuem o comportamento da plataforma.
Modelo do produto
ContractForge é útil quando uma equipe precisa do mesmo padrão de ingestão governada em runtimes de cliente ou corporativos, sem reescrever o framework para cada plataforma.
O que permanece portátil
A semântica portátil pertence ao contrato e ao núcleo:
- intenção de origem, intenção de destino e nomenclatura;
- append, overwrite, upsert/merge e intenção SCD;
- política de esquema;
- regras de qualidade;
- transformações e operações de shape que sejam neutras em termos de plataforma;
- anotações, propriedade, operações e intenção de acesso;
- requisitos de evidência.
O comportamento específico da plataforma pertence aos adaptadores. Databricks possui Delta, Unity Catalog, Auto Loader, Lakeflow, Jobs, Asset Bundles e auxiliares de runtime Databricks. AWS possui Glue Spark, Iceberg, artefatos S3, Lake Formation, MSK e APIs de runtime AWS. Snowflake possui execução em SQL warehouse, stages, procedures, tasks e governança nativa. Fabric possui Lakehouse notebooks, OneLake, shortcuts, pipelines e evidência Delta. GCP possui BigQuery, jobs de carga GCS, Workflows, Dataplex e evidência BigQuery.
Portabilidade honesta
ContractForge não promete que todo contrato rode em todo lugar. O planejador retorna um resultado explícito:
| Status | Significado |
|---|---|
SUPPORTED | O adaptador consegue preservar a semântica do contrato. |
SUPPORTED_WITH_WARNINGS | O adaptador consegue executar o plano, mas há diferenças documentadas ou ressalvas operacionais. |
REVIEW_REQUIRED | O adaptador encontrou um mapeamento possível, mas a troca semântica ou operacional deve ser aceita antes do deploy. |
UNSUPPORTED | O adaptador não consegue preservar o comportamento solicitado. |
Nenhum adaptador deve fazer downgrade silenciosamente de histórico para append, upsert para overwrite, filtros de linha para comentários ou evidências para logs de melhor esforço.
Seções de contrato
Ingestão
Origem, destino, modo de gravação, política de schema, qualidade, transformações, shape, watermarks e intenção de execução.
Anotações
Descrições, aliases, tags, classificação PII, metadados de ciclo de vida e documentação voltada para o catálogo.
Operações
Proprietário, grupo de suporte, criticidade, frequência, SLA, runbook e metadados operacionais.
Acesso
Concessões, filtros de linha, máscaras de coluna e política de desvio. O adaptador decide como a plataforma de destino os aplica.
Fronteiras dos pacotes
| Pacote | Responsabilidade |
|---|---|
contractforge-core | Modelos de contrato, validação, normalização semântica, correspondência de capacidades, planos abstratos, diagnósticos de portabilidade e modelos de evidências neutras. |
contractforge-databricks | Capacidades Databricks, renderização Delta/Unity Catalog/Lakeflow/Auto Loader, execução no runtime Databricks, Asset Bundles e preenchimento de evidências específicas da plataforma. |
contractforge-aws | Capacidades AWS Glue/Iceberg, publicação de artefatos S3, deploy de jobs Glue, auxiliares de revisão/aplicação Lake Formation e tabelas de evidência Iceberg. |
contractforge-snowflake | Capacidades Snowflake SQL warehouse, artefatos em stage, execução por procedure Snowpark, grafos de tasks, evidência nativa e auxiliares de revisão/aplicação de governança. |
contractforge-fabric | Execução de notebooks Fabric Lakehouse, expansão de origens OneLake, fontes externas com shortcuts, revisão de deployment pipeline e tabelas de evidência Delta. |
contractforge-gcp | Capacidades BigQuery, jobs de carga GCS, orquestração Workflows, qualidade/linhagem/aspectos Dataplex e tabelas de evidência BigQuery. |
O núcleo não importa Spark, Databricks SDK, boto3, Azure SDK, Fabric SDK, clientes Snowflake ou clientes GCP.
Prova real de paridade
O exemplo de medalhão USGS GeoJSON executa o mesmo desenho de ingestão bronze-to-gold em Databricks, AWS, Snowflake, Fabric e GCP. Ele mantém alinhados intenção de origem, ordem medalhão, regras de qualidade, comportamento de gravação, anotações, operações e evidências, enquanto as ligações de propriedade do adaptador selecionam tabelas nativas, referências SQL, caminhos de storage e pré-requisitos de runtime.
Na AWS, os contratos são renderizados e publicados no S3 antes da execução Glue. No Databricks, o adaptador executa pelo runtime Databricks. Snowflake prepara artefatos em stage e executa por caminhos SQL/procedure. Fabric implanta e executa notebooks Lakehouse gerados. GCP renderiza artefatos BigQuery/Workflows e pode executar a superfície BigQuery estável. A intenção do contrato permanece a mesma; somente o ambiente e as configurações de runtime de propriedade do adaptador mudam.
Comece aqui
Não objetivos
ContractForge não é um agendador, um wrapper Spark universal, um substituto de dbt, um produto GUI ou uma promessa de que cada plataforma tenha semântica idêntica. É o contrato, o planejamento, o adaptador e a camada de evidências para a ingestão governada repetível.