Critérios de superfície estável AWS

Propósito

Este documento define as condições verificáveis ​​para o tratamento contractforge-aws é estável para sua superfície aws_glue_iceberg suportada.

O portão tem escopo intencional. Não afirma que todo ContractForge a semântica suportada pelo adaptador de referência Databricks é certificada para produção em AWS. Diz que a superfície AWS Glue/Iceberg documentada aqui passou planejamento, renderização, implantação, tempo de execução, evidência, auditoria, ciclo de vida e verificações de paridade sem soluções alternativas específicas do contrato.

A matriz de evidências detalhada reside em aws-stabilization-matrix.md. Este arquivo é o lista de verificação de lançamento que converte esses resultados em uma decisão de estabilidade.

Scope

A superfície AWS estável é:

• Tempo de execução AWS Glue Spark;
• Apache Iceberg tables on Amazon S3;
• AWS Glue Data Catalog metadata;
• Evidência ContractForge como tabelas de controle legíveis por Iceberg/Athena;
• Lake Formation concede e avalia/candidata ajudantes onde a equivalência é comprovada ou explicitamente necessária para revisão.

Famílias de origem estáveis:

• S3/arquivos de armazenamento de objetos e formatos de arquivo portáteis;
• incremental_files usando marcadores Glue quando elegível;
• JDBC/Postgres through Glue JDBC paths;
• caminhos rest_api e http_file limitados com SSRF e guardas de redirecionamento;
• os caminhos de streaming validados AWS MSK e Azure Event Hubs Kafka disponíveis agora.

Modos de gravação estáveis:

• append;
• overwrite;
• upsert;
• hash_diff_upsert como SUPPORTED_WITH_WARNINGS; o valor de referência é validadas, enquanto as declarações SLA específicas da carga de trabalho exigem evidências anexadas.

Limites excluídos ou específicos da carga de trabalho:

• historical;
• snapshot_reconcile_soft_delete;
• expressões arbitrárias de filtro de linha Lake Formation e máscara de coluna além do reviewed consumer matrix;
• reivindicações do provedor de compatibilidade não-MSK Kafka/Event Hubs além do validado paths.

Inherited Preconditions

Essas invariantes do repositório devem ser aprovadas antes que a estabilidade do AWS possa ser avaliada.

Precondition	Verification
Core não tem importações de plataforma	tests/test_core_platform_independence.py
Adaptadores não importam uns aos outros	tests/test_adapter_independence.py
O formato da embalagem pública é estável	tests/test_publication_packaging.py
As versões do pacote declaradas correspondem aos metadados	tests/test_package_version.py
A arquitetura AWS permanece de propriedade do adaptador	tests/test_aws_architecture.py
AWS capability docs stay in sync	tests/test_aws_capability_parity_docs.py
CI constrói a roda adaptadora AWS	Pacote .github/workflows/ci.yml/escopos completos

If any precondition fails, AWS stability evaluation is paused.

Stability Criteria

1. Portões locais e de renderização

O que deve ser mantido. Unidade, renderização, arquitetura, empacotamento e código gerado compilar portas passam para AWS.

Como verificar. Execute:

uv run pytest tests/test_aws_*.py tests/test_adapter_source_support.py tests/test_adapter_extension_docs.py tests/test_publication_packaging.py tests/test_package_version.py
uv run contractforge-aws deploy-project examples/real-world/supabase-jdbc-medallion/project.yaml --dry-run --summary-only

Status. met.

2. Projetos de sucesso em tempo de execução

O que deve ser válido. Os projetos de validação reais são executados por meio do ContractForge apenas comandos, sem edições do Glue Studio e sem código de tempo de execução manuscrito.

Projetos necessários:

• aws_supabase_jdbc_medallion;
• aws_usgs_rest_medallion;
• aws_s3_file_medallion;
• aws_incremental_files;
• aws_eventhubs_kafka_available_now;
• aws_msk_kafka_available_now.

Cada projeto deve criar/gravar tabelas Iceberg de destino, preencher ctrl_ingestion_runs, qualidade/estado/metadados/linhagem do registro quando aplicável, e preserve as contagens de linhas esperadas.

Como verificar. Use o fluxo AWS CLI no nível do projeto:

contractforge-aws deploy-project <project.yaml> --run --wait --record-cost-evidence --audit-evidence

Status. met.

3. Evidência de falha

O que deve ser mantido. Falhas controladas produzem evidências de falha na execução e são editadas evidência de erro, preservando a falha do tempo de execução original.

Casos necessários:

• credenciais inválidas ou ausentes;
• blocked REST/HTTP targets;
• aborto de qualidade;
• invalid merge key;
• caminho de origem ausente;
• falha de permissão de destino, quando disponível.

Como verificar. Execute o projeto de caminho de falha AWS com --accept-expected-failures e auditoria ctrl_ingestion_runs, ctrl_ingestion_errors e ctrl_ingestion_quality.

Status. met.

4. Auditoria de evidências

O que deve ser válido. As consultas de auditoria do Athena em tabelas de controle canônico passam por todos os projetos reais de validação.

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.

Como verificar.

contractforge-aws audit-evidence --database <evidence_database> --athena-output-location <s3-uri>

Status. met.

5. Paridade de plataforma

O que deve ser válido. A intenção de contrato ContractForge compartilhada produz o mesmo resultados lógicos em Databricks, AWS e Snowflake para o compartilhamento suportado superfície. As diferenças específicas do AWS são limitadas à ligação da fonte, ambiente, Configurações de armazém Iceberg e limites de revisão aceitos.

Como verificar.

uv run python -m tools.platform_parity.report
uv run pytest tests/test_platform_parity_contracts.py

Evidências reais de E2E dos mesmos contratos em todas as três plataformas devem ser anexado às notas de lançamento ou ao manifesto de evidências de lançamento em ../reports/aws-stable-surface-evidence.json.

Status. met para a superfície suportada.

6. Limites de segurança e tempo de execução

O que deve ser mantido.

• O núcleo não importa SDKs AWS.
• O pacote AWS base não importa boto3 avidamente.
• Os artefatos renderizados não contêm segredos de texto simples.
• A resolução de segredo em tempo de execução usa o Secrets Manager ou mecanismos de propriedade da plataforma.
• Os caminhos REST/HTTP rejeitam esquemas inseguros, hosts privados e redirecionamentos.
• O executor estável da biblioteca Glue valida o código de tempo de execução renderizado antes execução em processo.

Como verificar. Execute testes de arquitetura/segurança do AWS e mantenha a validação do AST tests around runtime/library_runner.py mandatory.

Status. met.

Limites abertos de certificação de produção

A superfície estável suportada está pronta e stable_final é verdadeiro para o reivindicação AWS Glue/Iceberg documentada. Reivindicações mais amplas permanecem exclusões explícitas ou workload-specific warnings:

Limite	Decisão atual	Fechamento necessário
hash_diff_upsert workload-specific performance	SUPPORTED_WITH_WARNINGS	Referência de referência aprovada; anexe evidências específicas da carga de trabalho antes de reivindicar um SLA de produção para um novo contrato hash-diff.
Non-MSK Kafka/Event Hubs compatibility providers	EXCLUDED_FROM_STABLE_FINAL	Matriz de deslocamento/ponto de verificação específica do provedor além dos caminhos validados AWS MSK e Azure Event Hubs Kafka.
Filtros e máscaras de linha Lake Formation	EXCLUDED_FROM_STABLE_FINAL	Matriz de mecanismo do consumidor passada para Athena e Glue Spark; expressões contratuais arbitrárias ainda exigem revisão antes de reivindicações específicas de carga de trabalho.
historical e snapshot_reconcile_soft_delete	EXCLUDED_FROM_STABLE_FINAL	Exclusão de escopo estável documentada até a implementação do tempo de execução e evidências de equivalência E2E serem anexadas.

Estes não são defeitos ocultos. Eles são limites explícitos sobre o que o AWS estável surface claims.

Machine-Readable Gate

Usar:

contractforge-aws stabilization-report

Resultado esperado de superfície estável:

• classification = STABLE_SUPPORTED_SURFACE;
• supported_surface_ready = true;
• stable_final = true para a reivindicação final estável documentada.
• evidence_manifest = docs/reports/aws-stable-surface-evidence.json.

Use --strict-final em fluxos de trabalho que devem impor o final estável documentado claim.