AWS Stabilization Matrix

Propósito

Esta especificação define a porta de lançamento para estabilizar o contractforge-aws adaptador. Não é um roteiro de possíveis recursos do AWS. É a lista de verificação que decide se o primeiro adaptador AWS pode ser chamado de estável para o suporte surface.

O alvo é aws_glue_iceberg:

• Tempo de execução AWS Glue Spark;
• Apache Iceberg tables on Amazon S3;
• AWS Glue Data Catalog metadata;
• artefatos de revisão opcionais do Lake Formation;
• As tabelas de evidências ContractForge persistiram como tabelas Iceberg.

O adaptador deve preservar a semântica central. Se um tempo de execução AWS não puder preservar um comportamento do contrato, o planejador ou renderizador deve retornar REVIEW_REQUIRED, SUPPORTED_WITH_WARNINGS ou UNSUPPORTED. Não deve desvalorizar silenciosamente o contrato.

Stabilization Scope

O escopo do candidato estável é intencionalmente menor do que a tese AWS completa.

Area	Escopo de candidato estável	Fora do escopo para candidato estável
Sources	s3, portable file formats, rest_api, http_file, jdbc/Postgres, incremental_files	AppFlow, DMS, conectores SaaS proprietários, streaming contínuo
Modos de gravação	append, overwrite, upsert, hash_diff_upsert	historical equivalence, snapshot soft delete
Qualidade	abortar, avisar, quarentena em nível de linha para regras suportadas, qualidade de expressão com aviso	garantias de dialeto de qualidade específico do motor
Preparation	shape parsing, arrays, columns, flattening, casts, standardization, derived columns, composite keys, deduplication	operações de forma não suportadas, como explosões inseguras de conjuntos de bronze
Evidência	execuções, erros, qualidade, quarentena, alterações de esquema, metadados, linhagem, estado, custo, operações	armazenamentos de evidências alternativos diferentes de Iceberg
Governança	Anotações do catálogo Glue e auxiliares conservadores de revisão/aplicação do Lake Formation	certificação automática de filtros de linha e máscaras de coluna em todos os consumidores
Implantação	simulação de projeto local, renderização, publicação de artefatos no S3, criação/atualização do trabalho Glue, início/espera do trabalho, implantação/início/espera no nível do projeto na ordem project.yaml	comportamento completo do agendador/orquestrador
Artifact size	o manifesto de implantação relata bytes/linhas por artefato, bytes de script de tempo de execução e um limite de aviso de tempo de execução de 256 KiB sem bloqueio	limites de tamanho de bloqueio rígido são uma porta de lançamento futura após benchmarks de tempo de execução

Projetos de teste necessários

O adaptador AWS não pode ser estabilizado apenas com testes de renderização. Esses projetos deve ser executado em uma conta AWS real usando apenas contratos, arquivos de ambiente e Comandos ContractForge. Os scripts Glue gerados podem ser inspecionados, mas não manual Glue Studio edits are allowed.

Projeto	Fonte	Objetivo principal	Resultado obrigatório
aws_supabase_jdbc_medallion	Supabase/Postgres JDBC	JDBC, segredos, leituras particionadas, diferença de estado atual/hash, quarentena de qualidade, dependências de medalhão	Mesas Iceberg de bronze, prata e ouro criadas com evidências de controle correspondentes
aws_usgs_rest_medallion	USGS GeoJSON REST API	Conector REST, análise de forma JSON, achatamento, promoção de medalhão	A resposta API chega e é transformada sem o código de solução alternativa Python
aws_s3_file_medallion	S3 CSV files	Formatos de arquivo portáteis, política de esquema, marcadores Glue, diferença de estado atual/hash, quarentena de qualidade e promoção SQL	First run processes seed files, rerun preserves deterministic counts, new files are picked up by bookmarks
aws_incremental_files	S3 incremental files	Teste de estresse de marcador/estado dedicado em várias ondas de upload e repetições sem novas entradas	A segunda execução ignora arquivos já processados; novos arquivos são coletados; reexecução sem nova entrada registra SKIPPED sem duplicar linhas
aws_failure_paths	Contratos ruins controlados e falhas de tempo de execução	Evidência de erro, evidência de falha na execução, redação	A execução do Glue falha nativamente e grava evidências redigidas do ContractForge
aws_eventhubs_kafka_available_now	Azure Event Hubs Kafka endpoint	Glue Streaming estruturado availableNow, progresso do ponto de verificação, quarentena de qualidade e evidência de fluxo	A primeira execução consome mensagens, a reexecução sem entrada grava zero linhas, o lote inválido coloca em quarentena linhas e, posteriormente, o lote válido é retomado do ponto de verificação

Os cenários hash-diff devem declarar merge_keys e uma estratégia de hash. merge_keys são a identidade de linha durável usada na cláusula Iceberg MERGE ON. Para tabelas governadas, prefira hash_keys como as colunas de conteúdo explícito usadas para calcular row_hash. Para tabelas largas, use hash_strategy: all_columns_except com hash_exclude_columns. O adaptador AWS sempre exclui declarações do usuário e ContractForge/colunas geradas pela estrutura a partir de hash e blocos hash_diff_upsert sem merge_keys com AWS_HASH_DIFF_MERGE_KEYS_REQUIRED.

Fluxo de implantação

Todo projeto de teste real deve usar o mesmo fluxo de operador:

contractforge-aws plan
  -> contractforge-aws render
  -> contractforge-aws publish-s3
  -> contractforge-aws deploy
  -> contractforge-aws start
  -> contractforge-aws wait

deploy pode combinar renderização, publicação e registro de trabalho quando environment.artifacts.uri é declarado. Esse atalho é válido apenas quando o os mesmos artefatos renderizados e definição de trabalho são observáveis ​​em S3.

Acceptance criteria:

• o contrato de ambiente possui o artefato S3 URI;
• scripts gerados, manifestos, contratos normalizados e divisão original os contratos são publicados no S3;
• As definições de tarefa Glue usam o ScriptLocation publicado;
• a execução do projeto tenta novamente ConcurrentRunsExceededException dentro do orçamento de espera declarado em vez de travar com uma pilha AWS SDK bruta;
• nenhum código de usuário é necessário dentro do Glue Studio;
• todos os padrões específicos da plataforma vêm de environment.parameters.aws ou reviewed extensions.aws.*;
• o pacote principal permanece livre de importações de AWS SDK.

Portão de sucesso em tempo de execução

Cada cenário de sucesso deve provar:

• a tabela Iceberg de destino é criada quando ausente;
• a tabela de destino é gravada por meio do mecanismo de gravação selecionado;
• as linhas lidas, escritas e colocadas em quarentena estão corretas;
• alterações de esquema são registradas quando colunas são adicionadas ou alterações de tipo são detected;
• evidências de qualidade são escritas para regras de aborto, alerta e quarentena;
• as regras de quarentena removem as linhas com falha antes da gravação do destino;
• ctrl_ingestion_runs.status = SUCCESS is written only after job.commit();
• write_committed é verdadeiro para execuções confirmadas com sucesso;
• metadados de origem, linhagem, estado e evidências de custo são preenchidos onde available.
• um marcador Glue executado sem novos registros de entrada ctrl_ingestion_runs.status = SKIPPED, qualidade_status = SKIPPED, skip_reason = no_new_input, rows_read = 0, rows_written = 0, write_committed = false e não execute a lógica de preparação/gravação que depende das colunas de origem.

Failure Gate

A matriz de falha deve incluir pelo menos estes casos:

Failure case	Comportamento esperado
invalid JDBC secret	A tarefa Glue falha; ctrl_ingestion_errors edita o segredo; ctrl_ingestion_runs.status = FAILED
faltando caminho de origem S3	A tarefa Glue falha; o caminho de origem é registrado sem credenciais
REST URL bloqueado ou esquema inválido	adaptador/tempo de execução rejeita antes de buscar
violação de aborto de qualidade	A tarefa Glue falha; evidências de qualidade registram a regra falhada
invalid merge key	o renderizador ou o tempo de execução falham antes da gravação insegura
falha de permissão de destino	A tarefa Glue falha; a evidência de erro é o melhor esforço e foi redigida

A evidência de falha deve preservar a exceção original. Se estiver escrevendo evidência de erro falhar, o trabalho gerado poderá registrar essa falha secundária, mas deverá aumentá-la novamente a exceção de tempo de execução original.

Auditoria de Tabela de Controle

Cada execução real deve ser auditada através das tabelas de evidências canônicas renderizadas de contractforge_core.evidence.

Tabelas obrigatórias:

• ctrl_ingestion_runs
• ctrl_ingestion_errors
• ctrl_ingestion_quality
• ctrl_ingestion_quarantine
• ctrl_ingestion_schema_changes
• ctrl_ingestion_metadata
• ctrl_ingestion_lineage
• ctrl_ingestion_access
• ctrl_ingestion_operations
• ctrl_ingestion_cost
• ctrl_ingestion_state
• ctrl_ingestion_locks

Consultas mínimas de validação do Athena:

SELECT status, count(*) AS runs
FROM "<evidence_database>"."ctrl_ingestion_runs"
GROUP BY status;

SELECT quality_status, count(*) AS runs
FROM "<evidence_database>"."ctrl_ingestion_runs"
GROUP BY quality_status;

SELECT target_table, count(*) AS quality_rows
FROM "<evidence_database>"."ctrl_ingestion_quality"
GROUP BY target_table;

SELECT target_table, count(*) AS quarantined_rows
FROM "<evidence_database>"."ctrl_ingestion_quarantine"
GROUP BY target_table;

SELECT target_table, count(*) AS errors
FROM "<evidence_database>"."ctrl_ingestion_errors"
GROUP BY target_table;

SELECT cost.target_table, count(*) AS cost_rows, sum(cost.signal_value) AS glue_dpu_seconds
FROM "<evidence_database>"."ctrl_ingestion_cost" cost
INNER JOIN "<evidence_database>"."ctrl_ingestion_runs" runs
  ON runs.run_id = cost.run_id
 AND runs.target_table = cost.target_table
WHERE cost.signal_name = 'glue_dpu_seconds'
GROUP BY cost.target_table;

A auditoria deve comparar a evidência AWS com o projeto de paridade Databricks quando o a mesma intenção de contrato é testada em ambos os adaptadores.

O comando do operador suportado para esta auditoria é:

uv run contractforge-aws audit-evidence `
  --database <evidence_database> `
  --athena-output-location s3://<bucket>/athena-results/

O comando executa a consulta padrão definida acima por meio de AthenaSqlRunner e retorna os grupos de linhas como JSON, incluindo linhas de custo quando elas foram reconciliado. É um auxiliar de validação somente leitura; não cria evidências tabelas ou alterar o estado do tempo de execução.

A evidência de custo é uma etapa explícita de reconciliação pós-execução porque Glue JobRun Os segundos do DPU estão disponíveis no AWS API depois que o trabalho chega a um terminal estado, não de dentro do script Glue gerado. As execuções do projeto podem ser aceitas com:

uv run contractforge-aws deploy-project <project.yaml> `
  --run `
  --wait `
  --record-cost-evidence `
  --athena-output-location s3://<bucket>/athena-results/

Isso grava apenas linhas ctrl_ingestion_cost. Não duplica ctrl_ingestion_runs; a tarefa Glue gerada permanece como proprietária da evidência de execução. A reconciliação armazena a linha de custo sob o ID de execução canônico ContractForge (job_name:glue_run_id) e preserva o ID de execução bruto do Glue na carga útil para consultas de auditoria e benchmark podem juntar custos para executar evidências sem contar registros de plataforma órfã.

IAM e porta de segurança

O candidato estável do adaptador AWS deve passar nestas verificações:

• nenhuma importação de AWS SDK de contractforge_core;
• nenhuma importação ansiosa de boto3 do caminho de importação base do contractforge_aws;
• nenhum segredo de texto simples em artefatos renderizados;
• referências secretas são resolvidas por meio de mecanismos secretos de ambiente/tempo de execução;
• trabalhos gerados editam mensagens de exceção e rastreamentos de pilha antes da evidência writes;
• Os buscadores REST e HTTP rejeitam esquemas não suportados, hosts inseguros e redirecionamentos;
• Os artefatos de política IAM do trabalho Glue são modelos de revisão de privilégio mínimo, não blanket * policies;
• Os artefatos IAM incluem origem, warehouse, artefato, script e dependência S3 limites derivados do contrato/ambiente;
• Os filtros de linha e máscaras de coluna Lake Formation permanecem REVIEW_REQUIRED, a menos que o adaptador tem uma garantia de motor testada para o consumidor.

Performance Gate

Para o escopo compatível, capture pelo menos:

• Glue version;
• tipo de trabalhador e contagem de trabalhadores;
• Segundos DPU ou sinal de custo de trabalho equivalente;
• contagem de linhas de origem;
• contagem de linhas escritas alvo;
• quarantined row count;
• merge key cardinality;
• Instantâneo Iceberg antes e depois da gravação;
• job duration;
• generated job script size.

O renderizador deve incluir *.performance_profile.json e *.performance.sql artefatos para modos de gravação sensíveis ao tempo de execução. O perfil define as métricas e casos de referência para capturar. O SQL relata essas execuções de ctrl_ingestion_runs e ctrl_ingestion_cost. Esses artefatos não substituem a real AWS benchmark.

hash_diff_upsert remains SUPPORTED_WITH_WARNINGS until Glue/Iceberg merge o desempenho é validado sob um volume de atualização representativo e simultâneo o risco de gravação está documentado.

Release Gates

Gate	Requirement	Status values
G0 local suite	Testes de unidade e renderização aprovados	PASS, FAIL
Compilação de renderização G1	Todos os projetos reais são renderizados e compilações Python geradas	PASS, FAIL
Fluxo de implantação G2	Artefatos publicados no registro/atualização de trabalhos S3 e Glue	PASS, FAIL
Tempo de execução de sucesso do G3	Projetos reais necessários concluídos com sucesso	PASS, FAIL
Tempo de execução de falha G4	A matriz de falha grava erros redigidos e evidências de falha na execução	PASS, FAIL
G5 control audit	As tabelas de evidências correspondem às contagens e status esperados	PASS, FAIL
G6 parity	As diferenças contratuais Databricks/AWS/Snowflake relevantes para a superfície estável AWS são documentadas e mínimas	PASS, REVIEW_REQUIRED, FAIL
G7 docs	Os documentos, especificações e site do usuário AWS refletem o comportamento testado	PASS, FAIL
G8 lifecycle	Os recursos de nuvem de teste real têm um plano de limpeza não destrutivo e documentado	PASS, FAIL

O adaptador não é estável até que todas as portas sejam PASS, exceto as explicitamente aceitas REVIEW_REQUIRED parity items.

O comando de status legível por máquina é:

uv run contractforge-aws stabilization-report

A classificação de liberação pretendida é STABLE_SUPPORTED_SURFACE com supported_surface_ready: true e stable_final: true para o documentado Reivindicação AWS Glue/Iceberg. O benchmark de produção de hash-diff de referência é validadas, enquanto as declarações SLA específicas da carga de trabalho ainda exigem evidências anexadas. Compatibilidade não-MSK Kafka, expressões Lake Formation arbitrárias e A exclusão reversível de histórico/instantâneo são exclusões explícitas do final estável, a menos que certificado separadamente. Os trabalhos de CI podem executar stabilization-report --strict-final, que sai de zero enquanto esta reivindicação final estável documentada permanece satisfeita.

Rastreador de estabilização

Item	Status atual	Observações
Testes de unidade do adaptador local AWS	PASS	Os testes de renderização e auxiliar passam localmente.
Renderização do projeto/compilar simulação	PASS	deploy-project --dry-run --summary-only valida planejamento, renderização e compilação Python para arquivos Supabase, USGS, S3, arquivos incrementais e projetos de caminho de falha sem chamadas AWS API. Cada etapa executável agora compila o executor da biblioteca estável mais o script de revisão gerado.
Tempo de execução do executor da biblioteca AWS	PASS	Concluído em 02/06/2026 em arquivos S3, arquivos incrementais, USGS REST, Supabase JDBC, caminho de falha e projetos de streaming disponíveis agora. Todas as definições de tarefa Glue registradas apontaram para runtime/contractforge_aws_runner.py; os artefatos <target>.glue_job.py gerados permaneceram como artefatos de revisão/substituição.
Projeto Real Supabase JDBC AWS	PASS	Concluído em 02/06/2026 por meio de deploy-project --run --wait --record-cost-evidence --audit-evidence, utilizando apenas contratos, ambiente e adaptador CLI. Todos os cinco trabalhos Glue foram bem-sucedidos no runner estável, os status de qualidade bronze permaneceram QUARANTINED, os status de qualidade downstream permaneceram PASSED, a auditoria não mostrou linhas de erro e as evidências de custo foram registradas para cada destino.
Projeto real USGS REST AWS	PASS	Concluído em 02/06/2026 por meio de deploy-project --run --wait --record-cost-evidence --audit-evidence. Todos os quatro trabalhos Glue foram bem-sucedidos por meio do executor estável, a auditoria mostrou todas as execuções históricas bem-sucedidas, todos os status de qualidade PASSED, nenhuma linha de quarentena, nenhuma linha de erro e linhas de custo de segundo DPU unidas para todos os quatro destinos.
Projeto de arquivo S3	PASS	Concluído em 02/06/2026 por meio de deploy-project --run --wait --record-cost-evidence --audit-evidence. Todos os três trabalhos Glue foram bem-sucedidos no executor estável; as contagens de alvos permaneceram bronze = 7, prata = 7, ouro = 3; a auditoria registra evidências de sucesso, qualidade, quarentena e custos.
Projeto de arquivos incrementais	PASS	Concluído em 02/06/2026 por meio de deploy-project --run --wait --record-cost-evidence --audit-evidence. A última execução foi bem-sucedida através do executor estável em relação ao estado do marcador existente e às evidências de custo/auditoria registradas; a evidência histórica preserva a onda 1, a onda 2 e as execuções do SKIPPED sem novas entradas.
Projeto de caminho de falha	PASS	Concluído em 02/06/2026 após ensure-evidence-tables criar tabelas de evidências/estados Athena Iceberg. deploy-project --run --wait --accept-expected-failures --record-cost-evidence --audit-evidence produziu duas execuções de EXPECTED_FAILURE Glue através do executor estável, linhas de execução com falha, evidência de erro para ambos os alvos, evidência de qualidade de aborto para quality_abort_orders e evidência de custo de segundo DPU para ambos os alvos.
Evidência de streaming disponível agora	PASS	Real Azure Event Hubs através da validação do protocolo Kafka concluída em 02/06/2026 usando examples/real-world/aws-eventhubs-kafka-available-now; AWS MSK Validação sem servidor concluída em 10/06/2026 e registrada em docs/reports/aws-kafka-provider-matrix.json. Ambos os caminhos usaram comandos ContractForge e o executor estável, retiveram evidências de fluxo com pontos de verificação, registraram evidências de custo de segundo DPU e passaram na auditoria do Athena nas tabelas de execução, qualidade, quarentena, erros e custos. MSK é o provedor de maturidade Kafka nativo do AWS; provedores de compatibilidade não MSK ainda exigem revisão específica do provedor antes de reivindicações de compatibilidade mais amplas.
Auditoria de tabela de controle	PASS	Supabase, USGS, arquivo S3, arquivos incrementais, caminho de falha e projetos de streaming disponíveis agora foram auditados por meio do Athena usando tabelas de evidências ContractForge.
Revisão de IAM/segurança	PARTIAL_PASS	Os modelos IAM derivam limites de origem, warehouse, artefato, script e dependência S3 do contrato/ambiente; trabalhos de tempo de execução executados na função Glue configurada, mas a aplicação de política de privilégio mínimo permanece de propriedade da revisão.
Performance profile	PARTIAL_READY	Planejador avisa sobre hash_diff_upsert; render emite um perfil de benchmark e o manifesto de implantação expõe o tamanho do artefato gerado. O projeto CLI reconciliou Glue DPUSeconds em ctrl_ingestion_cost para o conjunto de benchmark AWS de arquivos incrementais: carga inicial 278.0, subconjunto alterado 290.0, execuções ignoradas 184.0, 234.0, 242.0; o rollup de auditoria une cinco IDs de execução canônicos por 1228.0 DPU segundos. A evidência de benchmark Supabase JDBC expôs e corrigiu a divisão da chave hash-diff: merge_keys agora conduz identidade de linha, comparação explícita de conteúdo de unidade hash_keys ou hash_strategy: all_columns_except e colunas geradas são excluídas automaticamente. As repetições de produtos de bronze real em 01/06/2026 validaram ambos os caminhos: status=SKIPPED, skip_reason=no_hash_changes, rows_written=0 retornados sem alteração, ID de instantâneo Iceberg inalterado e hash_diff_candidate_rows=0; uma mutação de origem de 10 linhas retornou status=SUCCESS, um novo ID de instantâneo Iceberg e hash_diff_candidate_rows=10. Os contadores de reescrita de arquivos físicos Iceberg permanecem separados das contagens de candidatos de negócios. Os benchmarks de concorrência ainda precisam de evidências mais amplas do volume de produção.
Cleanup lifecycle	PASS	contractforge-aws cleanup-project renderiza um plano de limpeza não destrutivo do project.yaml, incluindo nomes de tarefas Glue, prefixos S3 de artefato e armazém, banco de dados de evidências e recursos externos declarados. O projeto de streaming Event Hubs declara o grupo de recursos do Azure usado pelo namespace Event Hubs compatível com Kafka.
Docs/site update	PASS	A evidência de tempo de execução é registrada nesta matriz, nos documentos do adaptador AWS e no site de documentação.