Adaptador AWS

O adaptador AWS é a segunda família de adaptadores ContractForge. Seu primeiro alvo é aws_glue_iceberg: AWS Glue Spark jobs que escrevem tabelas Apache Iceberg no Amazon S3, catalogados no AWS Glue Data Catalog e governados pelo AWS Lake Formation.

O adaptador não é uma abstração AWS genérica. É um conjunto de sub-alvos AWS explícitos, cada um com suas próprias capacidades e limites de revisão.

Status atual: superfície suportada estável para o documentado Destino aws_glue_iceberg. Supabase JDBC, USGS REST, medalhão de arquivo S3, arquivos incrementais dedicados, caminhos de falha controlados e os validados o caminho de streaming disponível agora concluiu a validação de tempo de execução real do AWS por meio Comandos ContractForge e o executor de biblioteca estável. Referência hash-diff e A validação do mecanismo do consumidor Lake Formation agora faz parte das evidências de lançamento. exclusão reversível de histórico e instantâneo são explicitamente excluídas do final estável, enquanto reivindicações de compatibilidade de provedor de streaming não MSK e específicas de contrato as expressões de governação continuam a ser áreas explícitas de revisão ou validação.

O portão de liberação para chamar este adaptador de estável é rastreado em Critérios de superfície estável AWS, com os detalhes matriz de evidências em Matriz de estabilização AWS. Tempo de execução o comportamento deve ser descrito como suportado apenas quando tiver passado por esses portões, não apenas porque o renderizador pode produzir um artefato.

Cada renderização inclui um artefato *.deployment_manifest.json. O manifesto registra bytes e lines por artefato, um artifact_summary e um artifact_size_budget que marca scripts Glue gerados WARN acima de 256 KiB, para que as revisões possam acompanhar o crescimento do trabalho gerado no Glue antes de publicar no S3.

A tarefa Glue implementada padrão usa o executor da biblioteca ContractForge AWS. O o script de trabalho é o artefato runtime/contractforge_aws_runner.py estável; o contrato e ambiente são publicados como artefatos JSON de tempo de execução e passados ​​como Argumentos Glue. O executor carrega esses artefatos de tempo de execução dentro do Glue, renderiza o corpo Glue/Spark revisado com o mesmo renderizador do adaptador e o executa em o processo Glue. O <target>.glue_job.py gerado permanece parte de cada renderizar apenas para revisão e validação de sintaxe; A implantação do AWS Glue sempre aponta para o executor da biblioteca estável.

Contratos com modos de gravação sensíveis ao tempo de execução, atualmente hash_diff_upsert, também renderizar artefatos *.performance_profile.json e *.performance.sql. O perfil é o plano de medição necessário; o SQL é um relatório compatível com Athena sobre ctrl_ingestion_runs e ctrl_ingestion_cost para as execuções de benchmark. Nenhum dos dois é um resultado de referência por si só. Eles definem as evidências necessárias para promover o mapeamento AWS de SUPPORTED_WITH_WARNINGS para uma produção mais forte claim.

O *.iam_policy.json gerado é um modelo de revisão, não aplicado automaticamente política. Ele deriva o catálogo Glue, CloudWatch Logs, fonte S3, armazém Iceberg, artefato S3, script Glue e permissões de arquivo de dependência do contrato e ambiente. Arquivos de dependência e caminhos de script explícitos são renderizados como exatos ARNs do objeto S3; locais de origem, artefato e armazém permanecem com escopo de prefixo onde o tempo de execução deve ler ou gravar vários objetos.

Evidência de tempo de execução capturada em 02/06/2026:

Projeto	Resultado	Evidência
Supabase JDBC medallion	PASS	Projeto AWS somente de contrato concluído por meio do adaptador CLI e do runtime/contractforge_aws_runner.py estável com cinco trabalhos Glue bem-sucedidos. A última execução gravou evidências de custo para todos os cinco alvos, reteve o comportamento de quarentena de bronze e a auditoria não mostra linhas de erro.
USGS REST medallion	PASS	Medalhão REST/GeoJSON concluído através do deploy-project --run --wait --record-cost-evidence --audit-evidence usando o runner estável. A auditoria mais recente mostra 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.
S3 file medallion	PASS	Três trabalhos Glue passaram pelo executor estável, as linhas de destino permaneceram bronze = 7, prata = 7, ouro = 3 e a auditoria registra evidências de sucesso, qualidade, quarentena e custo.
Incremental files	PASS	O projeto de arquivo incremental foi executado no executor estável e registrou uma execução bem-sucedida do marcador existente com evidências de custo/auditoria; as execuções históricas preservam as evidências da onda 1, onda 2 e SKIPPED sem novas entradas.
Failure paths	PASS	ensure-evidence-tables criou tabelas de evidência/estado Athena Iceberg e, em seguida, duas falhas esperadas de Glue foram executadas no executor estável com EXPECTED_FAILURE, linhas de execução com falha, evidência de erro, evidência de qualidade de aborto e evidência de custo de segundo DPU para ambos os alvos.
Available-now streaming	PASS	Os trabalhos disponíveis agora do Azure Event Hubs e AWS MSK Kafka foram executados no executor estável com streaming Glue com pontos de verificação, status de sucesso, evidência de custo e auditoria do Athena sobre execução, qualidade, quarentena, erros e tabelas de custos.

Alvo Inicial

Area	Decision
Subtarget	aws_glue_iceberg
Tempo de execução	AWS Glue Spark
Formato de tabela	Apache Iceberg
Storage	Amazon S3
Catalog	AWS Glue Data Catalog
Governança	AWS Lake Formation
Evidência	Tabelas de evidências Iceberg

Por que Glue + Iceberg primeiro

Este caminho fornece ao ContractForge um tempo de execução gerenciado do Spark, um formato de tabela aberto com semântica ACID, um catálogo API e uma camada de governança que pode expressar controles de linhas e colunas.

Ele também mantém o adaptador AWS alinhado com a tese principal:

same contract intent
same planning model
different native runtime artifacts
same evidence concepts

Superfície Suportada

O adaptador alimenta o núcleo público API sem dependências AWS SDK no pacote base. Ele renderiza scripts Glue Spark/Iceberg, revisa artefatos e estruturas de implantação para a superfície suportada abaixo.

Feature	Resultado do planejamento	Renderização em tempo de execução
append	SUPPORTED	Glue Script Spark com acréscimo Iceberg
overwrite	SUPPORTED	Glue Script Spark com criação/substituição de Iceberg
upsert	SUPPORTED	Glue Script Spark com Iceberg MERGE INTO e protetores de chave
hash_diff_upsert	SUPPORTED_WITH_WARNINGS quando merge_keys mais hash_keys ou hash_strategy: all_columns_except são declarados; UNSUPPORTED sem merge_keys	Glue Script Spark com cálculo de hash de linha e Iceberg MERGE INTO; merge_keys define a identidade da linha e a estratégia de hash define o conteúdo comparado; desempenho/simultaneidade ainda precisa de validação AWS
historical	REVIEW_REQUIRED	Apenas artefato de revisão
snapshot_reconcile_soft_delete	REVIEW_REQUIRED	Apenas artefato de revisão
Filtros de linha	REVIEW_REQUIRED	Apenas revisão Lake Formation
Máscaras de coluna	REVIEW_REQUIRED	Apenas revisão Lake Formation
available-now streaming	SUPPORTED para caminhos AWS MSK e Azure Event Hubs Kafka validados; SUPPORTED_WITH_WARNINGS para outros provedores de compatibilidade	Tarefa de streaming estruturado Glue com readStream, trigger(availableNow=True) e foreachBatch para modos de acréscimo/mesclagem quando checkpoint_location é declarado
incremental_files	SUPPORTED_WITH_WARNINGS	Glue DynamicFrame lido com marcadores de trabalho para formatos S3 elegíveis; marcador sem nova entrada executa evidência de registro SKIPPED sem executar lógica de preparação/gravação dependente de coluna
JDBC incremental	SUPPORTED_WITH_WARNINGS	Glue DynamicFrame lido com jobBookmarkKeys quando uma coluna de marca d'água simples é mapeada para um tipo de conexão Glue JDBC
Databricks autoloader	UNSUPPORTED; usar incremental_files	None
native_passthrough	REVIEW_REQUIRED	Revise o artefato de transferência com recomendações de caminho AWS, como conectores AppFlow, DMS, Glue nativos/personalizados ou conectores de parceiro

A renderização de qualidade de tempo de execução preserva a política de aplicação ContractForge para regras de qualidade de dados Glue mapeadas. As verificações abortadas de required_columns, unique_key e row_count_minimum falham na execução. Regras de aviso como max_null_ratio gravam evidências ctrl_ingestion_quality e continuam. A quarentena em nível de linha é implementada para not_null e accepted_values: as linhas com falha são gravadas em ctrl_ingestion_quarantine, removidas do dataframe antes da gravação de destino e contadas na evidência de execução. As regras de expressão são avaliadas como Spark SQL verificações de tempo de execução com SUPPORTED_WITH_WARNINGS: anular falha na execução, avisar evidências de registros e quarentena grava linhas com falha em ctrl_ingestion_quarantine antes de filtrá-las. O aviso permanece porque a portabilidade do dialeto de expressão deve ser revista.

Para hash_diff_upsert, não use hash_keys como chaves comerciais. O adaptador AWS requer merge_keys para identidade de linha. Use hash_keys para conteúdo explícito colunas em tabelas governadas ou hash_strategy: all_columns_except mais hash_exclude_columns para tabelas largas. O renderizador exclui automaticamente colunas geradas pelo ContractForge/framework, como row_hash, Colunas de controle source_loaded_at_utc, SCD e saídas de transform.derive ou transform.composite_keys. Ele também pré-filtra linhas inalteradas antes de Iceberg MERGE e registra gravações sem alteração como SKIPPED com skip_reason=no_hash_changes. Os resumos de snapshot Iceberg relatam contadores de reescrita de arquivos, como added-records e deleted-records; para observabilidade de hash-diff, o ContractForge também escreve hash_diff_candidate_rows e hash_input_columns em operation_metrics_json. Os painéis devem usar hash_diff_candidate_rows para volume de mudança de negócios e contadores Iceberg para amplificação de armazenamento/gravação.

A renderização de preparação de tempo de execução preserva shape.parse_json portátil, shape.arrays, shape.columns, shape.flatten, transform.cast, transform.standardize, transform.derive, transform.composite_keys e transform.deduplicate determinístico. O adaptador ainda bloqueia semântica de forma/transformação não suportada, como shape.zip_arrays e explosão de matriz de camada de bronze sem uma permissão explícita de cardinalidade, portanto, não ignora silenciosamente a análise, a explosão de matriz ou a semântica de desduplicação.

O dispositivo dedicado de arquivos incrementais reside em examples/real-world/aws-incremental-files. Utiliza apenas contratos e um AWS arquivo de ambiente para validar o planejamento incremental_files, marcador Glue configuração, renderização Iceberg e compilação Python gerada antes do O teste de tempo de execução da onda de upload é executado em AWS. O verdadeiro teste AWS cobre a onda 1, onda 2 e uma repetição sem novas entradas; a última execução deve preservar a linha de destino conte e escreva evidências SKIPPED com skip_reason = no_new_input.

Os trabalhos de streaming disponíveis agora registram linhas por microlote em ctrl_ingestion_streams e copie os totais agregados do fluxo para o final ctrl_ingestion_runs.operation_metrics_json as stream_batches, stream_rows_read, stream_rows_written e stream_rows_quarantined. Final evidências escritas em linhas de execução, estado e linhagem preferem o fluxo ContractForge total porque o snapshot Iceberg mais recente pode representar apenas o último microlote. Os caminhos AWS MSK e Azure Event Hubs Kafka foram validados em AWS Glue com progressão de checkpoint, repetições sem entrada, quarentena ou alvo escreve e custa evidências. MSK é o provedor de maturidade Kafka nativo do AWS. Outro Provedores compatíveis com Kafka/Event Hubs ainda retornam um aviso de revisão do provedor até que a semântica do conector/tempo de execução seja testada.

Implantação do Projeto

AWS segue o vocabulário de comando do adaptador padronizado em Adaptador CLI. Para repositórios de ingestão reais, use o nível do projeto comandos: deploy-project carrega project.yaml, resolve environments.aws e implanta contratos em execution_order; run-project inicia da mesma forma gráfico do projeto. As simulações executam o carregamento do projeto, o planejamento do contrato, o artefato renderização e compilação de sintaxe Python para scripts Glue gerados sem AWS API calls.

--summary-only mantém implantação, execução, espera, status de custo, contagens de artefatos e bytes, but omits verbose per-artifact S3 lists.

Quando AWS Glue rejeita temporariamente uma etapa do projeto com ConcurrentRunsExceededException, deploy-project novas tentativas começam dentro do mesmo orçamento --max-wait-seconds usando --poll-interval-seconds. Isto mantém o caminho do operador determinístico sob simultaneidade no nível da conta ou no nível do trabalho limites sem exigir intervenção manual do Glue Studio.

Orquestração de projetos nativos

A orquestração do projeto AWS é de propriedade do adaptador e baseada em Step Functions. O contrato YAMLs são planejados e renderizados antes da implantação e, em seguida, publicados com o executor estável da biblioteca AWS. Glue executa esse executor estável por padrão e recebe o contrato URI como argumento. Quando a orquestração nativa é solicitado, o adaptador mapeia project.yaml.execution_order em uma máquina de estado do Step Functions que inicia os trabalhos Glue registrados com a integração Glue .sync. Passos no mesmo dependency wave are emitted as a Parallel state.

Se project.yaml.schedule for declarado, a carga útil de orquestração também inclui um destino do EventBridge Scheduler para a máquina de estado. Real a implantação requer funções de propriedade do AWS:

• parameters.aws.step_functions.role_arn para a máquina de estado;
• parameters.aws.scheduler.role_arn para EventBridge Scheduler quando agendar are deployed.

Este é o AWS equivalente ao caminho do projeto Databricks DAB, mas em AWS nativo termos: Databricks cria um trabalho multitarefa; AWS cria trabalhos Glue por contrato além de uma máquina de estado Step Functions que os orquestra.

Use a sintaxe cron padrão no arquivo de projeto e um nome de fuso horário IANA. O AWS O adaptador renderiza a expressão do EventBridge Scheduler internamente:

schedule:
  cron: "0 6 * * *"
  timezone: America/Sao_Paulo
  enabled: false
  adapters:
    aws:
      state: DISABLED

O exemplo acima torna-se cron(0 6 * *? *) para AWS. Somente nativo de AWS substituições como state, flexible_time_window ou expression pertencem a schedule.adapters.aws.

Sinalizadores de execução direta Glue (--run / --wait) são intencionalmente mutuamente exclusivo com flags de execução do Step Functions (--run-orchestration/ --wait-orchestration) para evitar executar os mesmos contratos duas vezes.

Projetos com caminho de falha podem declarar expected_result: failed em uma etapa e executar com --accept-expected-failures. Isso se destina a testes de observabilidade que provam ctrl_ingestion_errors e falharam no ctrl_ingestion_runs sem manually editing generated Glue code.

O comando audit-evidence específico do AWS executa as verificações da tabela de controle padrão a partir do sistema de estabilização matriz: execuções por status, execuções por status de qualidade, linhas de qualidade por destino, linhas de quarentena por destino, linhas de erro por destino e Glue reconciliado DPU-segundo linhas de custo por destino. Os acúmulos de custos unem ctrl_ingestion_cost a ctrl_ingestion_runs em run_id e target_table, portanto, custo da plataforma órfã registros não são contados.

Glue JobRun cost signals are reconciled after a terminal run because DPUSeconds está disponível no AWS API, não dentro da tarefa Glue gerada. Use --record-cost-evidence com execuções de projeto aguardadas para anexar Linhas ctrl_ingestion_cost sem duplicar ctrl_ingestion_runs. O o adaptador registra o custo sob o ID de execução canônico ContractForge (job_name:glue_run_id) e mantém o ID de execução bruto do Glue na carga útil.

Para uma execução Glue já concluída, registre a evidência de custo sem executar novamente o trabalho de ingestão com o auxiliar record-glue-cost específico do AWS.

O comando usa o mesmo gravador de custos idempotente que deploy-project --record-cost-evidence. Se o contrato não for adjacente ao seu .environment.yaml, passe --environment explicitamente para que o comando grave o banco de dados de evidências pretendido.

Para contratos sensíveis ao tempo de execução, como hash_diff_upsert, use o método canônico Comando performance-report para renderizar o benchmark SQL localmente ou executá-lo through Athena after benchmark runs.

cleanup-project não exclui nada. Ele lê o mesmo projeto e contratos de ambiente, renderiza os nomes de trabalho Glue esperados, prefixo do artefato S3, prefixo S3 do armazém, banco de dados de evidências e qualquer limpeza externa declarada recursos. O exemplo de streaming Event Hubs declara o grupo de recursos do Azure usado pelo namespace Event Hubs compatível com Kafka, portanto, a saída de limpeza inclui o comando az group delete revisado sem executá-lo.

A prontidão para lançamento é relatada por meio do stabilization-report canônico comando.

O relatório separa duas reivindicações. supported_surface_ready: true e classification: STABLE_SUPPORTED_SURFACE significa o AWS Glue/Iceberg documentado superfície ultrapassou os portões do projeto real. stable_final: true significa tudo preocupações de certificação de produção dentro dessa declaração documentada são certificadas ou explicitly excluded. Broader claims such as non-MSK Kafka compatibility, SLAs hash-diff específicos do contrato, expressões Lake Formation arbitrárias, histórico e a exclusão reversível do instantâneo permanecem fora do final estável, a menos que evidências separadas sejam attached. O manifesto de evidências legível por máquina é publicado em docs/reports/aws-stable-surface-evidence.json. Use --strict-final no CI para impor a declaração final estável documentada.

Limite do pacote

O pacote é publicado de forma independente:

contractforge-core
contractforge-aws

Dependency direction:

contractforge-aws -> contractforge-core
contractforge-core -> no AWS dependency

O pacote base não deve importar clientes boto3, Lake Formation ou SDKs AWS. AWS Os auxiliares de execução API pertencem ao extra opcional runtime:

contractforge-aws[runtime]

Os scripts Glue renderizados podem importar módulos de tempo de execução Glue porque essas importações residem dentro dos artefatos gerados, e não dentro do caminho de importação do pacote do adaptador.

Public Entry Points

Planejamento/renderização principal e auxiliares de tempo de execução AWS opcionais:

from contractforge_aws import (
    AthenaSqlRunner,
    AWSAdapter,
    deploy_aws_contract_to_glue,
    plan_aws_contract,
    publish_aws_contract_artifacts_to_s3,
    register_aws_glue_job,
    register_aws_glue_job_definition_payload,
    apply_aws_lake_formation_contract,
    apply_aws_annotations_contract,
    ensure_aws_evidence_tables,
    record_aws_operations_contract,
    render_aws_contract,
    render_aws_deployment_manifest,
    render_aws_glue_job_cloudformation,
    render_aws_glue_job_definition,
    render_aws_glue_job_iam_policy,
    render_aws_glue_job_terraform,
    start_aws_glue_job_run,
    wait_aws_glue_job_run,
)
from contractforge_aws.capabilities import glue_iceberg_capabilities

result = plan_aws_contract(contract, subtarget="aws_glue_iceberg")
artifacts = render_aws_contract(contract)
manifest = render_aws_deployment_manifest(contract)
job_payload = render_aws_glue_job_definition(contract)
cloudformation = render_aws_glue_job_cloudformation(contract)
terraform = render_aws_glue_job_terraform(contract)
sql_runner = AthenaSqlRunner(database="contractforge_ops", output_location="s3://query-results/")

published = publish_aws_contract_artifacts_to_s3(contract, bucket="contractforge-artifacts", prefix="dev/orders")
deployment = deploy_aws_contract_to_glue(contract, environment=environment_contract)
registered = register_aws_glue_job(
    job_name="cf-orders",
    role_arn="arn:aws:iam::123456789012:role/ContractForgeGlueRole",
    script_s3_uri="s3://contractforge-artifacts/dev/orders/glue_bronze_orders.glue_job.py",
    enable_job_bookmark=True,
)
registered_from_payload = register_aws_glue_job_definition_payload(job_payload, glue_client=my_glue_client)
run = start_aws_glue_job_run(job_name="cf-orders", arguments={"--contractforge-run-id": "run-123"})
status = wait_aws_glue_job_run(job_name="cf-orders", run_id=run.run_id)
lf_result = apply_aws_lake_formation_contract(contract, lakeformation_client=my_lf_client)
annotation_result = apply_aws_annotations_contract(contract, glue_client=my_glue_client)
setup_result = ensure_aws_evidence_tables(runner=my_sql_runner, database="contractforge_ops")
operations_result = record_aws_operations_contract(runner=my_sql_runner, contract=contract, run_id="run-123")

O CLI aceita o mesmo contrato de ambiente utilizado pelo Python API. Quando o caminho de entrada é um pacote dividido, como orders.ingestion.yaml, o orders.environment.yaml adjacente é carregado automaticamente. Um --environment path/to/prod.environment.yaml explícito substitui o ambiente do pacote configurável para plan, render e publish-s3.

contractforge-aws plan contracts/orders.ingestion.yaml
contractforge-aws render contracts/orders.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws publish-s3 contracts/orders.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws deploy contracts/orders.ingestion.yaml --environment environments/prod.aws.yaml

O environment.evidence.database resolvido é usado consistentemente por trabalhos Glue gerados, evidência/estado DDL, custo operacional SQL, recursos de revisão de política IAM, CloudFormation, Terraform e o manifesto de implantação. O arquivo de ambiente seleciona o local da tabela de evidências/controle; a semântica de ingestão ainda vem apenas da ingestão, anotações, operações e contratos de acesso.

environment.parameters.aws.glue_job, environment.parameters.aws.job_bookmarks e environment.parameters.aws.dependencies podem fornecer padrões de implantação em nível de ambiente. O extensions.aws.* no nível do contrato substitui esses padrões para uma ingestão específica.

O adaptador já padroniza a versão Glue 4.0, tipo de trabalhador G.1X, dois trabalhadores, tempo limite de 60 minutos, zero tentativas, modo executor de biblioteca e marcador habilitação da semântica de origem. Declare esses campos somente quando o projeto precisa substituir os padrões.

environment.artifacts.uri pode fornecer o destino S3 para Glue gerado scripts, manifestos, arquivos de contrato de tempo de execução e originais/normalizados opcionais instantâneos do contrato:

adapter: aws
artifacts:
  uri: s3://contractforge-artifacts/prod/orders/
  include_contract_bundle: true
  include_normalized_contract: true
parameters:
  aws:
    iceberg:
      warehouse: s3://contractforge-warehouse/prod/
    dependencies:
      extra_py_files:
        - s3://contractforge-artifacts/libs/contractforge_aws.whl
    glue_job:
      role_arn: arn:aws:iam::123456789012:role/ContractForgeGlueRole

Quando artifacts.uri é declarado, publish-s3 e deploy não precisam de um argumento de intervalo/prefixo separado. O adaptador analisa o destino, publica os artefatos renderizados e materializa a definição da tarefa Glue com o resultado final published ScriptLocation.

deploy é o atalho operacional para o caminho AWS:

load bundle
  -> plan/render
  -> publish artifacts to S3
  -> materialize Glue job definition
  -> create or update Glue job

A plataforma ainda executa trabalhos nativos Glue. O núcleo nunca importa SDKs AWS; o carregamento do contrato em tempo de execução é propriedade do contractforge-aws dentro do Glue.

Ajudantes de evidências públicas também aceitam environment=. Se um auxiliar receber database= e environment=, o database explícito vencerá.

A renderização produz artefatos de revisão, um executor de biblioteca AWS estável e corpos de tarefa Glue Spark para append, overwrite, upsert e hash_diff_upsert quando o contrato não contém semântica que exigiria comportamento de tempo de execução não suportado. As fontes Kafka/Event Hubs já disponíveis são renderizadas como tarefas Glue de streaming estruturado para modos de gravação compatíveis com acréscimo e mesclagem quando a semântica do ponto de verificação é explícita. As definições de tarefa Glue incluem a extensão Iceberg Spark de propriedade do adaptador --conf; os chamadores podem adicionar a configuração Spark revisada por meio do extensions.aws.glue_job.spark_conf, mas não podem substituir as configurações do Iceberg de propriedade do adaptador.

Os contratos renderizáveis ​​também recebem:

• .deployment_manifest.json: manifesto determinístico listando artefatos gerados, ordem de aplicação, limites de revisão, auxiliares de tempo de execução opcionais e tamanhos de artefatos gerados;
• runtime/contractforge_aws_runner.py: executor Glue estável usado por implantações padrão;
• .glue_job_definition.json: deterministic Glue create/update payload;
• .cloudformation.json: scaffold CloudFormation parametrizado para bancos de dados e jobs Glue;
• .terraform.tf: scaffold Terraform parametrizado para bancos de dados e trabalhos Glue;
• .iam_policy.json: revise o modelo de política IAM para a função gerada.
• .performance.sql: consulta de evidência de benchmark para mapeamentos sensíveis ao tempo de execução such as hash_diff_upsert.

O manifesto de implantação inclui um orçamento de tamanho de script de tempo de execução sem bloqueio. Isto relata o executor estável e os bytes de trabalho Glue gerados e marca o orçamento de artefato de tempo de execução WARN acima de 256 KiB, portanto, grandes trabalhos gerados são visible during review before they become operational risk.

Cada renderização também inclui Iceberg DDL para tabelas canônicas de evidência/controle ContractForge. Esses esquemas vêm do contractforge_core.evidence; o adaptador AWS apenas os mapeia para Glue Catalog/Iceberg DDL. Os trabalhos Glue gerados criam as tabelas de evidências necessárias, registram o estado como observações AWS somente anexadas e acrescentam evidências finais de execução bem-sucedida somente após Glue job.commit() e após a conclusão das evidências de estado, metadados e linhagem. Os caminhos de falha gravam evidências ctrl_ingestion_errors editadas e uma linha FAILED em ctrl_ingestion_runs com write_committed = false; se a gravação da evidência falhar, a tarefa registrará essa falha secundária e gerará novamente a exceção original.

Os primeiros auxiliares de tempo de execução opcionais publicam artefatos renderizados no S3, registram/atualizam definições de trabalho AWS Glue, iniciam execuções de trabalho Glue, inspecionam o status da execução e mapeiam metadados Glue JobRun em objetos de registro de evidências principais. Eles importam boto3 preguiçosamente apenas quando o chamador não fornece um cliente AWS, portanto, o planejamento/renderização permanece livre de SDK.

O registro da tarefa Glue pode usar parâmetros explícitos ou a carga útil determinística .glue_job_definition.json renderizada pelo adaptador. O registro de carga útil remove campos somente para revisão antes de chamar Glue.

Os auxiliares de aplicação Lake Formation são intencionalmente conservadores. As subvenções de tabela são diretamente aplicáveis ​​a partir do plano prestado. Os filtros de células de dados são ignorados por padrão e exigem allow_data_cells_filters=True e um account_id concreto, porque os filtros de linha e as máscaras de coluna permanecem semânticas exigidas pela revisão.

Glue Os auxiliares de aplicação da anotação de catálogo leem a definição da tabela atual e enviam um TableInput completo preservado por meio de UpdateTable; eles não emitem atualizações parciais de metadados que possam eliminar o descritor de armazenamento, a partição ou as propriedades da tabela.

Os auxiliares de gravação de operações aceitam um executor SQL de propriedade do chamador e executam a inserção canônica ctrl_ingestion_operations renderizada pelo adaptador. Eles são auxiliares de tempo de execução, não um comportamento de agendador/orquestrador.

Os auxiliares de configuração de evidências aceitam um executor SQL de propriedade do chamador e executam o mesmo Iceberg DDL renderizado de contractforge_core.evidence para execuções, erros, qualidade, quarentena, esquema, metadados, linhagem, acesso, operações, custos e tabelas de estado. A configuração da evidência requer um executor SQL em espera porque as instruções DDL do banco de dados e da tabela são ordenadas.

AthenaSqlRunner é fornecido como encanamento de tempo de execução opcional para esses auxiliares de execução SQL. Ele inicia consultas do Athena por meio de um cliente AWS fornecido pelo chamador ou criado lentamente. Auxiliares de instrução única podem enviar de forma assíncrona, mas a configuração da evidência aguarda a conclusão.

A passagem nativa permanece apenas para revisão. O artefato AWS recomenda caminhos de serviço concretos e entradas de revisão necessárias, mas não executa APIs do conector AppFlow, DMS ou Glue e não certifica a semântica de origem proprietária.

Iniciar uma tarefa Glue por meio do auxiliar de tempo de execução opcional ainda não é uma orquestração ContractForge completa. Os trabalhos gerados persistem em sua própria execução e evidência de qualidade nas tabelas de controle Iceberg, enquanto a reconciliação AWS JobRun pós-execução permanece um auxiliar explícito para revisão de evidências suplementares de execução/custo.

A espera de execução do Glue está disponível como um auxiliar fino sobre o GetJobRun; ele retorna no SUCCEEDED e aumenta em estados terminais com falha. Ele não tenta novamente, reinicia ou reconcilia evidências automaticamente.

Os mesmos auxiliares de tempo de execução são expostos por meio do pacote CLI para operadores que preferem implantação orientada por shell:

contractforge-aws register-glue-job-payload .contractforge/orders.glue_job_definition.json

contractforge-aws wait-glue-job \
  --job-name cf-orders \
  --run-id jr_123 \
  --max-wait-seconds 3600

contractforge-aws register-glue-job \
  --job-name cf-orders \
  --role-arn arn:aws:iam::123456789012:role/ContractForgeGlueRole \
  --script-s3-uri s3://contractforge-artifacts/dev/orders.glue_job.py \
  --enable-job-bookmark

contractforge-aws ensure-evidence-tables \
  --database contractforge_ops \
  --athena-output-location s3://contractforge-query-results/athena/ \
  --warehouse-uri s3://contractforge-lakehouse/evidence/

contractforge-aws audit-evidence \
  --database contractforge_ops \
  --athena-output-location s3://contractforge-query-results/athena/

contractforge-aws apply-annotations contracts/customers.yaml --catalog-id 123456789012

contractforge-aws apply-lakeformation contracts/customers.yaml --account-id 123456789012

contractforge-aws record-operations contracts/customers.yaml \
  --database contractforge_ops \
  --run-id run-123 \
  --athena-output-location s3://contractforge-query-results/athena/

O adaptador também expõe um runner de smoke manual e com custo mínimo:

contractforge-aws smoke \
  --account-id 123456789012 \
  --bucket contractforge-aws-smoke-123456789012-us-east-1 \
  --max-estimated-cost-usd 1.00 \
  --execute \
  --wait

Sem --execute, o comando é uma simulação e imprime o contrato gerado, os caminhos esperados do S3 e o teto de custo baseado no tempo limite. Este comando intencionalmente não faz parte do CI normal.

Development Phases

Fase 1: Esqueleto de Planejamento

• Adicione documentos e ADR.
• Adicione o esqueleto do pacote contractforge-aws.
• Add aws_glue_iceberg capabilities.
• Adicione o adaptador API e revise a renderização.
• Adicione testes para comportamento com suporte, aviso, revisão obrigatória e sem suporte.

Phase 2: Rendering

• Renderize scripts Glue Spark para acréscimo, substituição, upsert do estado atual e hash-diff.
• Preparação portátil de renderização: seleção, renomeação, filtro, conversão, padronização, colunas derivadas, chaves compostas, desduplicação determinística, análise JSON, matrizes, colunas e nivelamento.
• Renderize verificações de qualidade mapeadas com semântica de aplicação ContractForge: abortar, alertar evidências e quarentena em nível de linha.
• Renderize evidência/estado Iceberg DDL a partir do esquema principal da tabela de controle.
• Renderize scaffolds de revisão/aplicação do Lake Formation.
• Renderize a definição de trabalho IAM, Glue, os scaffolds de implantação CloudFormation e Terraform como artefatos de revisão.

Fase 3: Protótipo de Tempo de Execução

• Publique artefatos renderizados no S3 por meio do contractforge-aws[runtime].
• Registre/atualize definições de tarefa Glue com uma função IAM explícita e script publicado URI.
• Inicie execuções de trabalho Glue e inspecione o status sem reconciliação automática de evidências.
• Mapeie metadados Glue JobRun em objetos principais RunEvidenceRecord e CostEvidenceRecord.
• Renderize Iceberg INSERT SQL para evidência de execução/custo reconciliada sem aplicá-la automaticamente.
• Execute caminhos Glue/Iceberg de acréscimo, substituição e upsert do estado atual em uma conta AWS controlada.
• Valide S3, JDBC, HTTP, REST, fluxo limitado, fluxo disponível agora e caminhos de origem de compartilhamento Delta.
• Escreva tabelas de evidências Iceberg.
• Valide o comportamento da política de qualidade e esquema.

Fase 4: Mesclagem e comparação de hash

• Valide Iceberg MERGE INTO por meio de Glue Spark em dados de tamanho de produção e simultaneidade.
• Mantenha a implementação de hash-diff alinhada com a semântica central de hash.
• Adicione diagnósticos de desempenho e simultaneidade.

Fase 5: Governança e modos avançados

• Valide filtros de dados Lake Formation para Athena e outros consumidores.
• Avalie a exclusão reversível de histórico e instantâneo.
• Adicione design de passagem nativo para AppFlow/DMS.

Documentação

Contrato de arquitetura: especificações do adaptador AWS

Researched capability matrix: AWS capability parity

Registro de decisão: Adaptador ADR-007 AWS Glue Iceberg