Contratos portáveis para ingestão governada.

Uma camada semântica para declarar intenção uma vez, executar nativamente em Databricks, AWS, Snowflake, Fabric e GCP, e registrar evidência sem esconder diferenças de plataforma.

contract-first multi-runtime evidence-driven sem downgrade silencioso

A tese do projeto

A intenção de ingestão deve ser estável. A execução deve ser nativa.

O contrato descreve o que precisa acontecer. O adapter preserva essa intenção usando os recursos reais da plataforma.

Por que isso existe

Cada plataforma ensina o time a escrever a mesma ingestão de novo.

Delta, Glue, Iceberg, Snowpark, Lakehouse, BigQuery, Workflows, Dataflow. O runtime muda, mas a intenção de negócio costuma ser a mesma.

Efeito

Duplicação

Contratos, jobs e validações divergem por plataforma.

Efeito

Migração cara

A lógica fica presa ao runtime original.

Efeito

Governança frágil

Qualidade e evidência viram pós-processamento.

Efeito

Confiança baixa

O usuário não sabe se houve downgrade semântico.

Como o ContractForge pensa

Três camadas, três responsabilidades.

01

Semântica comum

Fonte, destino, escrita, qualidade, transformação, acesso, operações e evidência.

02

Binding nativo

Catálogo, schema, bucket, warehouse, Lakehouse, role, policy e runtime.

03

Diagnóstico honesto

Suportado, suportado com avisos, requer revisão ou não suportado.

Fluxo mental

Do contrato à evidência.

Contrato YAMLIntenção revisável.

CoreNormalização e validação.

PlannerCapacidade e semântica.

AdapterArtefatos nativos.

RuntimeExecução na plataforma.

EvidênciaAuditoria, qualidade e lineage.

O core não precisa carregar Spark, boto3, Snowpark, Fabric API ou BigQuery client. Esse acoplamento pertence aos adapters.

Contrato como fonte da verdade

O YAML declara a intenção, não o motor.

Um contrato carrega leitura, destino, camada, modo, política de schema, transformação, qualidade e evidência esperada.

source:
  type: rest_api
  request:
    method: GET
  response:
    mode: raw

target:
  schema: cf_usgs_rest_bronze
  table: b_usgs_earthquake_geojson

layer: bronze
mode: overwrite
schema_policy: permissive

USGS GeoJSON

O bloco de fonte é o mesmo para todos os adapters.

source:
  type: rest_api
  name: usgs_earthquake_2_5_day_geojson
  system: usgs
  request:
    url: https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson
    method: GET
    headers:
      Accept: application/geo+json, application/json
      User-Agent: ContractForge real ingestion test
  response:
    mode: raw
    raw_column: raw_response
  limits:
    timeout_seconds: 60
    retry_attempts: 3
    max_records: 1

O que permanece igual

A superfície reutilizável é maior que a diferença entre plataformas.

Parte	Intenção compartilhada
Fonte	`source.type: rest_api`, mesma URL, mesmo método, mesmo raw response.
Escrita	`layer: bronze`, `mode: overwrite`, `schema_policy: permissive`.
Qualidade	`required_columns`, `not_null` e `unique_key`.
Medallion	Bronze raw, silver normalizado, gold agregado.

O que muda

O endereço físico muda. A intenção não.

Databricks

target:
  catalog: workspace
  schema: cf_usgs_rest_bronze
  table: b_usgs_earthquake_geojson
extensions:
  databricks:
    delta_properties:
      delta.enableChangeDataFeed: "true"

AWS

target:
  catalog: contractforge
  schema: cf_usgs_rest_bronze
  table: b_usgs_earthquake_geojson
extensions:
  aws:
    iceberg:
      warehouse: s3://.../warehouse/usgs-rest/

Mais três runtimes, mesma intenção

Snowflake

target:
  catalog: CONTRACTFORGE_TEST_DB
  schema: PUBLIC
  table: CF_USGS_REST_BRONZE

Fabric

target:
  catalog: workspace
  schema: cf_usgs_rest_bronze
  table: b_usgs_earthquake_geojson

GCP BigQuery

target:
  catalog: midyear-system-499521-p3
  schema: contractforge_gcp_usgs_rest_bronze
  table: b_usgs_earthquake_geojson

Essa é a fronteira correta: a semântica é portável, o runtime continua nativo.

Projeto, não arquivo solto

A ordem bronze → silver → gold também é contrato.

O `project.yaml` declara ambientes, dependências e quais arquivos representam a mesma etapa em cada adapter.

execution_order:
  - name: bronze_usgs_geojson
    layer: bronze
    depends_on: []
    contracts:
      databricks: contracts/databricks/bronze/...
      aws: contracts/aws/bronze/...
      snowflake: contracts/snowflake/bronze/...
      fabric: contracts/fabric/bronze/...
      gcp: contracts/gcp/bronze/...

  - name: silver_usgs_events
    depends_on: [bronze_usgs_geojson]

  - name: gold_usgs_daily_summary
    depends_on: [silver_usgs_events]

USGS end-to-end

O exemplo real não para no bronze.

Bronze

Raw GeoJSON

Resposta REST armazenada em `raw_response` com paginação e qualidade mínima.

Silver

Eventos normalizados

Explode, cast, padronização, deduplicação e campos derivados.

Gold

Agregações

Resumo diário e bandas de magnitude para consumo analítico.

O que já funciona

Superfícies estáveis, com limites explícitos.

Componente	Estado	Superfície
Core	Ativo	Modelo semântico, validação, planejamento e evidência.
Databricks	Referência	Delta, Unity Catalog, Auto Loader, Lakeflow, Jobs e dashboards.
AWS	Stable supported surface	Glue Spark, Iceberg, S3, Lake Formation e evidência.
Snowflake	Stable supported surface	SQL warehouse, Snowpark procedure, tasks, qualidade e evidência.
Fabric	Stable supported surface	Lakehouse, notebooks, source expansion, governança e evidência.
GCP	Stable supported surface	BigQuery, GCS, BigLake, Dataplex, Workflows e evidência.

A parte mais importante

Adapter não é tradutor cego.

O adapter deve preservar semântica, avisar, pedir revisão ou bloquear. Nunca transformar historical em append, merge em append ou segurança em comentário.

SUPPORTED

Executa preservando a intenção.

SUPPORTED_WITH_WARNINGS

Executa, mas há caveat não destrutivo.

REVIEW_REQUIRED

Precisa de decisão humana ou privilégio especial.

UNSUPPORTED

Não há equivalência segura.

Além de REST

JDBC com upsert, deduplicação, derive e quarentena.

O contrato carrega lógica de ingestão real, não apenas metadados decorativos.

source:
  type: connection
  connection_path: project://connections/supabase.yaml
  table: cf_supabase_newcore_demo.product_movements

layer: bronze
mode: upsert
schema_policy: additive_only
merge_keys: [movement_uid]
on_quality_fail: quarantine

transform:
  composite_keys:
    movement_uid: [product_id, movement_seq]
  derive:
    movement_value: quantity * unit_cost
    movement_date: to_date(event_ts)
  deduplicate:
    keys: [movement_uid]

Qualidade não é pós-processamento

As regras entram no plano, no runtime e na evidência.

Cada adapter precisa decidir como materializar as regras sem perder a intenção original.

quality_rules:
  not_null:
    - movement_uid
    - product_id
    - event_ts
  unique_key:
    - movement_uid
  accepted_values:
    movement_type:
      - inbound
      - outbound
      - adjustment
  expressions:
    - name: non_zero_quantity
      expression: quantity <> 0
      severity: quarantine

Streaming com fronteira clara

Kafka existe, mas a equivalência é tratada por provider e runtime.

AWS, Databricks, Fabric e GCP têm caminhos validados em superfícies específicas. Snowflake mantém Kafka/Snowpipe/Streams como decisão separada.

source:
  type: kafka_available_now
  system: confluent_cloud
  bootstrap_servers: pkc-619z3.us-east1.gcp.confluent.cloud:9092
  topic: cf-databricks-orders
  checkpoint_location: /Volumes/.../checkpoints/...
  starting_offsets: earliest

layer: bronze
mode: append
schema_policy: additive_only

Evidence as product surface

A ingestão não termina na tabela.

runstatus, tempos, linhas, runtime e operação.

qualityregras avaliadas, falhas e quarentena.

schemapolítica aplicada e mudanças observadas.

lineageorigem, destino e evento compatível com auditoria.

Governança e custo entram quando a plataforma expõe sinais confiáveis.

Sinais reais do repo

O exemplo USGS roda como projeto em múltiplos adapters.

Fabric

SUCCEEDED

Projeto REST bronze → silver → gold validado em Lakehouse notebooks.

GCP

SUCCEEDED

BigQuery executou carga, SQL, qualidade, evidência, lineage e governança planejada.

Contrato

Sem workaround

O relatório registra quando o teste usou contratos declarados, não código paralelo para passar.

ContractForge AI

A IA ajuda a interpretar intenção. Ela não bypassa o crivo.

O provider pode explicar, enriquecer e sugerir. Quem decide validade é o fluxo determinístico: intent, core, planner e adapter.

1

Prompt

Usuário descreve o projeto.

2

Parâmetros

A intenção vira entrada aceitável.

3

Validação

Core e adapters bloqueiam incoerências.

4

Review

Saída consolidada em `AI_REVIEW.html`.

O relatório oficial

`AI_REVIEW.html` existe para aprovação técnica.

Pedido

O que foi interpretado a partir do prompt.

Projeto

Arquivos gerados, contexto e contratos.

Decisões

Itens pendentes agrupados por ocorrência e escopo.

Validação

Checks determinísticos e status de readiness.

IA

Orientação advisory separada da decisão determinística.

Evidência

Arquivos, contexto, riscos e próximos passos.

Onde ele se posiciona

Não é dbt, Airbyte ou catálogo. É outra camada.

Ferramenta	Foco	Diferença
dbt	Transformação depois que o dado chegou.	ContractForge governa chegada, escrita, qualidade e evidência.
Airbyte	Conectores e replicação.	ContractForge foca semântica portável e runtime nativo.
Fivetran	ELT gerenciado.	ContractForge preserva contrato e ambiente do cliente.
Catálogos	Metadados.	ContractForge leva metadados para o fluxo de execução governada.

Onde faz mais sentido

O valor aparece quando portabilidade, governança e evidência importam.

Consultorias que entregam em stacks diferentes.
Times de plataforma que querem padronizar ingestão.
Empresas em migração entre clouds ou data platforms.
Data products com SLA, lineage, qualidade e governança.
Projetos em que "funcionou" não basta; é preciso provar como funcionou.

Mensagem final

Defina a intenção. Preserve a semântica. Execute nativamente. Registre evidência.

E nunca esconda o que precisa de revisão.

Essa é a proposta do ContractForge: portabilidade honesta para ingestão governada.