Especificação do adaptador AWS

Propósito

O adaptador AWS traduz contratos semânticos ContractForge em planejamento nativo de AWS, renderização e, em fases posteriores, artefatos de execução.

O roteiro de implementação é informado pela matriz de paridade AWS pesquisada em paridade de capacidade AWS. Essa matriz deve ser atualizada sempre que Glue, Iceberg, Lake Formation, qualidade de dados ou recursos do conector nativos do AWS mudarem.

A estabilização do tempo de execução é governada pela matriz de estabilização AWS. Essa matriz é a porta de liberação para projetos reais do AWS, evidências de caminhos de falhas, auditorias de tabelas de controle e verificações de reforço de produção.

O destino inicial do adaptador é aws_glue_iceberg:

• tempo de execução: AWS Glue Spark;
• formato de tabela: Apache Iceberg no Amazon S3;
• catalog: AWS Glue Data Catalog;
• governança: AWS Lake Formation;
• evidência: tabelas de evidências Iceberg, com artefatos S3 JSON como substituto/exportação futura.

O adaptador começa com planejamento e renderização, mas agora inclui tempo de execução limitado ajudantes para publicação de artefato, registro de trabalho Glue, início/status do trabalho Glue inspeção e validação de smoke com custo controlado. As implantações padrão do Glue usam um script executor da biblioteca AWS estável que recebe artefato de contrato/ambiente URIs como argumentos Glue. O executor carrega o contrato publicado dentro do Glue, usa o renderizador do adaptador como base de compatibilidade e executa o renderizado Corpo Glue/Spark no processo Glue. O caminho de importação base permanece livre de SDK; AWS Os auxiliares API exigem o tempo de execução extra opcional ou clientes fornecidos pelo chamador.

Design Principles

• O núcleo não importa SDKs boto3, AWS ou bibliotecas Glue.
• O pacote básico do adaptador AWS não requer boto3; AWS Os ajudantes do API vivem atrás de um extra de tempo de execução opcional.
• As escolhas específicas do AWS são expressas por meio de recursos, diagnósticos e artefatos do adaptador.
• Os sub-alvos AWS são explícitos. Não existe uma declaração de capacidade genérica "AWS pode fazer tudo".
• Os marcadores de tarefa Glue são detalhes de implementação do adaptador, não semântica central.
• Os mapeamentos Lake Formation começam de forma conservadora porque os mecanismos de consumo, as concessões IAM e LF afetam o comportamento.
• A evidência deve preservar o modelo de evidência central mesmo quando AWS o persiste de forma diferente de outras plataformas.

Subtargets

Subtarget	Status	Purpose
aws_glue_iceberg	Meta inicial	Glue Tarefas Spark que gravam tabelas Apache Iceberg em S3 com metadados do catálogo Glue.
aws_athena_iceberg	Future	Renderização e diagnóstico orientados a SQL para cargas de trabalho Athena/Iceberg. Não é um executor geral.
aws_emr_serverless_iceberg	Future	Tempo de execução avançado do Spark para tarefas que precisam de mais controle de tempo de execução do que o Glue.
aws_native_passthrough	Future	Serviços de ingestão nativos do AWS, como AppFlow, DMS ou conectores gerenciados.

Initial Capabilities: aws_glue_iceberg

O modelo de capacidade principal atual usa booleanos conservadores. O primeiro adaptador AWS mapeia o destino AWS mais rico em PlatformCapabilities da seguinte forma:

PlatformCapabilities(
    platform="aws_glue_iceberg",
    supports_append=True,
    supports_overwrite=True,
    supports_merge=True,
    supports_hash_diff=True,
    supports_scd2=True,
    supports_snapshot_reconcile_soft_delete=True,
    supports_schema_evolution=True,
    supports_row_filters=True,
    supports_column_masks=True,
    supports_available_now_streaming=True,
    supports_required_columns_quality=True,
    supports_unique_key_quality=True,
    supports_max_null_ratio_quality=True,
    supports_expression_quality=True,  # Spark SQL runtime checks, with dialect warning
    supports_shape=True,
    supports_transform=True,
    evidence_stores=("iceberg_table",),
    review_required_semantics=(
        "historical",
        "snapshot_reconcile_soft_delete",
        "row_filters",
        "column_masks",
        "source.native_passthrough",
    ),
)

Alguns booleanos são definidos como True para que o planejador principal possa retornar REVIEW_REQUIRED em vez de UNSUPPORTED para semântica que AWS pode implementar de forma plausível, mas que requer revisão. Esta é a mesma distinção que: "a plataforma possui primitivas, mas o adaptador não tem permissão para reivindicar equivalência semântica automaticamente". A qualidade da expressão é suportada pelas verificações de tempo de execução Spark SQL e retorna SUPPORTED_WITH_WARNINGS porque a portabilidade do dialeto da expressão ainda deve ser revisada.

Mapeamento do modo de gravação

Modo ContractForge	Initial status	AWS mapping	Notes
append	SUPPORTED	Glue Spark anexado à tabela Iceberg	O script Glue gerado cria a tabela Iceberg na primeira execução quando ela não existe e, em seguida, anexa nas execuções posteriores.
overwrite	SUPPORTED	Glue Spark cria/substitui na tabela Iceberg	O script Glue de primeira passagem é renderizado; regras de substituição de partição são comportamentos detalhados futuros.
upsert	SUPPORTED	Iceberg MERGE INTO de Glue Spark	O script Glue de primeira passagem é renderizado com proteções de chave ausente, chave nula e chave duplicada.
hash_diff_upsert	SUPPORTED_WITH_WARNINGS	Hash diff staging plus Iceberg merge	O script de tempo de execução é renderizado; o aviso permanece até que o desempenho e a simultaneidade do Glue/Iceberg sejam validados.
historical	REVIEW_REQUIRED	Iceberg merge/history implementation	Requer revisão de atrasos, exclusões e encontros efetivos.
snapshot_reconcile_soft_delete	REVIEW_REQUIRED	Full snapshot reconciliation in Iceberg	Requer prova de integridade da fonte e revisão de simultaneidade.

O renderizador gera scripts Glue Spark para append, overwrite, upsert e hash_diff_upsert quando as seções de preparação e qualidade podem ser preservadas. Ele também renderiza trabalhos de streaming disponíveis agora para fontes Kafka/Event Hubs suportadas e modos de gravação suportados. os modos histórico e instantâneo permanecem apenas para revisão até que sua implementação nativa seja validada.

Mapeamento de tempo de execução de preparação

O primeiro renderizador de tempo de execução AWS oferece suporte apenas à semântica de preparação que pode ser expressa direta e deterministicamente em um DataFrame Glue Spark antes das verificações e gravações de qualidade:

Campo de contrato	Comportamento do primeiro tempo de execução	Notes
select_columns	Rendered in Glue job	Falha antes da gravação se uma coluna selecionada estiver faltando.
column_mapping	Rendered in Glue job	Falha em colunas de origem ausentes, destinos duplicados, colunas de controle reservadas ou colisões de destino.
filter_expression	Rendered in Glue job	Applied as a Spark SQL filter expression.
transform.cast	Rendered in Glue job	Usa conversões Spark e falha em colunas de origem ausentes.
transform.standardize	Rendered in Glue job	Usa funções de string Spark para normalização de corte, inferior, superior, espaço em branco e vazio como nulo.
transform.derive	Rendered in Glue job	Usa expressões Spark SQL; O SQL multiplataforma complexo permanece como responsabilidade do chamador.
transform.composite_keys	Rendered in Glue job	Usa Spark concat_ws e comportamento nulo para vazio de acordo com a semântica de chave composta do contrato principal.
shape.parse_json	Rendered in Glue job	Requer um esquema concreto ou schema_ref resolvido; opcional cast_input: STRING é suportado.
shape.arrays	Rendered in Glue job	Suporta size, to_json, first, explode e explode_outer; explosões de bronze que alteram a cardinalidade exigem permissão explícita.
shape.columns	Rendered in Glue job	Suporta caminhos de coluna, aliases, conversões e expressões Spark SQL.
shape.flatten	Rendered in Glue job	Usa um auxiliar de introspecção de esquema em tempo de execução e mantém os arrays intactos.
transform.deduplicate	Rendered in Glue job	Requer keys e order_by determinísticos; renderiza uma janela Spark com row_number() == 1.

O adaptador não deve renderizar uma tarefa Glue executável que ignore shape ou transform. Se seções não suportadas estiverem presentes, o renderizador emite um artefato .glue_job.todo.md.

Mapeamento de tempo de execução de qualidade

O planejamento do AWS pode reconhecer ampla capacidade de qualidade porque Spark, Glue Data Quality e Iceberg podem expressar as verificações. A renderização em tempo de execução preserva a política de imposição quando o adaptador pode mapear a regra fielmente:

Regra de qualidade	Comportamento do primeiro tempo de execução	Notes
required_columns com gravidade abort	Rendered in Glue job	Avaliado com qualidade de dados Glue e falha na execução em caso de falha.
unique_key com gravidade abort	Rendered in Glue job	Avaliado com qualidade de dados Glue e falha na execução em chaves duplicadas.
row_count_minimum com gravidade abort	Rendered in Glue job	Avaliado com qualidade de dados Glue e falha na execução abaixo do limite.
not_null com gravidade quarantine	Rendered in Glue job	Os resultados de qualidade de dados Glue em nível de linha são gravados em ctrl_ingestion_quarantine; as linhas com falha são removidas antes da gravação.
accepted_values com gravidade quarantine	Rendered in Glue job	Os resultados de qualidade de dados Glue em nível de linha são gravados em ctrl_ingestion_quarantine; as linhas com falha são removidas antes da gravação.
max_null_ratio com gravidade warn	Rendered in Glue job	Os resultados são gravados em ctrl_ingestion_quality; a corrida continua.
expression	Renderizado no trabalho Glue com aviso	Avaliado como filtros Spark SQL; abortar falha na execução, avisar a evidência de qualidade dos registros e colocar em quarentena as linhas com falha e, em seguida, filtra-las antes de gravar. A portabilidade de dialeto permanece SUPPORTED_WITH_WARNINGS.

O adaptador não deve converter silenciosamente regras de quarentena ou de aviso em comportamento somente de anulação. A quarentena em nível de linha só é aplicada a regras em que o Glue Data Quality retorna resultados de linha que identificam linhas incorretas (not_null e accepted_values hoje). As regras agregadas de gravidade da quarentena são registradas como evidência de qualidade e não filtram linhas. Se houver semântica de qualidade não suportada, o renderizador emite um artefato .glue_job.todo.md em vez de um trabalho Glue executável.

Mapeamento de origem

Intenção de origem	Comportamento inicial do alvo AWS
table, view, sql	Referências de origem Glue Catálogo/Athena/Iceberg em planos renderizados.
file formats: csv, json, parquet, orc, text, avro	S3/Spark readers in Glue job script.
s3, object_storage, blob com provedor s3	Glue Spark lê S3.
incremental_files	Marcadores Glue ou estado de evidência ContractForge, dependendo do formato de origem e das regras de destino.
jdbc, postgres, mysql, sqlserver, oracle, redshift, db2	Glue Fonte JDBC com pré-requisitos de driver/rede.
http_file, http_csv, http_json, http_text	Busca limitada do lado do motorista ou padrão de pouso S3; o tempo de execução é de propriedade do adaptador.
kafka_bounded, eventhubs_bounded	Spark Kafka/Event Hubs limitado lido em Glue; os jars do conector e a semântica de deslocamento permanecem de propriedade do adaptador.
Databricks autoloader	UNSUPPORTED; use incremental_files para portabilidade.
native_passthrough	Revise/aplique a transferência para conectores nativos/personalizados AppFlow, DMS, Glue ou conectores de parceiros. O artefato recomenda caminhos AWS concretos e revisa entradas, mas permanece não executável.

Incremental Tracking

Os marcadores de tarefa Glue são uma otimização do adaptador AWS. O núcleo vê apenas a intenção da fonte, marcas d'água e requisitos de evidência.

Política inicial:

• As fontes JDBC podem mapear a intenção incremental principal para chaves de marcadores Glue quando a chave configurada é monotônica e suportada.
• O comportamento incremental da fonte S3 pode usar marcadores Glue para formatos suportados ou estado de evidência ContractForge.
• O adaptador deve registrar qual estratégia foi selecionada na saída e na evidência da revisão renderizada.

As tarefas Glue geradas comparam o esquema da tabela Iceberg de destino antes e depois da gravação confirmada. Colunas adicionadas e alterações de tipo detectadas são anexadas ao ctrl_ingestion_schema_changes e o mesmo resumo é copiado para ctrl_ingestion_runs.schema_changes_json.

Mapeamento de Governança

Os filtros de dados Lake Formation podem expressar controles em nível de coluna, em nível de linha e em nível de célula. O adaptador inicial marca filtros de linha e máscaras de coluna como REVIEW_REQUIRED porque o comportamento depende de:

• Lake Formation administrator setup;
• Data Catalog registration;
• Subsídios IAM e LF;
• consumer engine support;
• limites de expressão e tipo de dados suportados.

O renderizador deve gerar um artefato de revisão descrevendo os filtros de dados, concessões e suposições necessárias do Lake Formation antes que qualquer comando de aplicação exista.

Anotações e operações são seções do contrato, e não preocupações apenas do Lake Formation. O adaptador AWS os mapeia separadamente:

• annotations.table.description torna-se uma atualização planejada da descrição da tabela do catálogo Glue.
• annotations.table.tags, aliases e metadados de descontinuação tornam-se parâmetros planejados da tabela Glue.
• annotations.columns.*.description becomes planned Glue column comments.
• annotations.columns.*.tags, PII e metadados de descontinuação tornam-se parâmetros planejados da coluna Glue.
• Os metadados operations são persistidos na tabela de evidências canônica ctrl_ingestion_operations.

A aplicação de anotações ainda não é intencionalmente automática. Glue UpdateTable requer a preservação da definição da tabela atual e o envio de um TableInput completo, de modo que a primeira superfície do adaptador emita um plano explícito e evidências correspondentes SQL em vez de aplicar cegamente metadados parciais.

Mapeamento de evidências

O primeiro alvo de evidência de produção são as tabelas Iceberg registradas no Catálogo AWS Glue. O adaptador AWS deve renderizar essas tabelas a partir do contractforge_core.evidence; ele não deve bifurcar ou redefinir o esquema da tabela de controle.

Conceito de evidência	Alvo de persistência AWS
run	Tabela Iceberg no banco de dados de evidências
error	Tabela Iceberg no banco de dados de evidências
resultado de qualidade	Tabela Iceberg no banco de dados de evidências
quarantined row reference	Tabela Iceberg ou referência de objeto S3
mudança de esquema	Tabela Iceberg no banco de dados de evidências; trabalhos Glue gerados acrescentam colunas adicionadas e linhas de mudança de tipo após gravações confirmadas
lineage event	Tabela Iceberg mais exportação OpenLineage opcional
metadados de origem	campos de execução/evidência JSON
aplicação de governança	Tabela de auditoria Iceberg
cost signal	Métricas de execução de trabalho Glue e custo estimado de DPU

S3 Os artefatos JSON podem ser gerados para revisão e arquivamento, mas não são o armazenamento de evidências padrão. As tarefas Glue geradas criam tabelas de evidências e estados ausentes antes de gravá-las. Os caminhos de sucesso chamam Glue job.commit() antes de anexar a evidência final de sucesso e, em seguida, atualizam ctrl_ingestion_state e acrescentam ctrl_ingestion_runs, ctrl_ingestion_metadata e ctrl_ingestion_lineage; Os trabalhos de streaming disponíveis agora também acrescentam linhas por lote ao ctrl_ingestion_streams. A evidência de execução inclui descrição do contrato, proprietário, domínio, tags, SLA, parâmetros de tempo de execução, propriedade, metadados de operações, identidade de trabalho/execução Glue e identificadores de idempotência/grupo de execução quando declarada. Os trabalhos em lote capturam rows_read antes que os filtros de qualidade/quarentena alterem o dataframe, para que as linhas em quarentena não desapareçam das métricas de leitura. Os caminhos de falha acrescentam evidências de erro redigidas ao ctrl_ingestion_errors, acrescentam uma linha FAILED ao ctrl_ingestion_runs com write_committed = false e aumentam novamente para que a execução nativa do Glue ainda falhe. As gravações de evidências de erro são de melhor esforço: se a persistência da tabela de controle falhar, a tarefa gerada registrará a falha secundária e preservará a exceção original.

Environment Binding

O adaptador AWS pode consumir o contrato principal environment.

• environment.adapter deve ser aws.
• environment.evidence.database controla o banco de dados do Catálogo Glue usado para artefatos de evidências, estado, custo, metadados, linhagem e evidências de governança.
• environment.evidence.schema é aceito como um alias de compatibilidade para o mesmo conceito de banco de dados de evidências AWS porque o contrato de ambiente genérico é multiplataforma.
• environment.artifacts.uri controla o prefixo S3 usado para scripts renderizados, manifestos, contratos divididos originais e instantâneos de contratos normalizados.
• environment.parameters.aws é exposto ao adaptador como padrões nativos de propriedade do AWS. Esses parâmetros não devem alterar a semântica de ingestão.

O contrato de ambiente não altera origem, tabela de destino, modo de gravação, anotações, operações ou semântica de acesso.

Scripts de trabalho Glue gerados, scaffolds CloudFormation, scaffolds Terraform, artefatos de revisão de política IAM, evidências DDL, estado DDL, custo SQL e manifestos de implantação devem usar o mesmo banco de dados de evidências resolvido. Um plano renderizado com environment.evidence.database: cf_ops_prod não deve gravar evidências de tempo de execução no banco de dados <target>_ops substituto.

Os padrões de implantação podem ser declarados em environment.parameters.aws.glue_job, environment.parameters.aws.job_bookmarks e environment.parameters.aws.dependencies. Esses padrões alimentam artefatos de implantação, como definições de trabalho Glue, CloudFormation e Terraform, enquanto extensions.aws.* no contrato permanece a substituição por contrato. Argumentos Glue de propriedade do adaptador, como --datalake-formats, --enable-glue-datacatalog, --job-bookmark-option e argumentos de dependência gerados, permanecem reservados.

As funções auxiliares de evidências públicas aceitam o mesmo contrato ambiental. Quando database= e environment= são passados, o argumento explícito database vence porque é uma substituição intencional do chamador no limite do auxiliar.

AWS O planejamento e a renderização do CLI devem respeitar o mesmo limite. contractforge-aws plan, contractforge-aws render, contractforge-aws publish-s3 e contractforge-aws deploy carregam um .environment.yaml de pacote dividido adjacente automaticamente quando o caminho do contrato é uma seção dividida. O argumento --environment explícito substitui esse ambiente de pacote configurável. Os comandos de aplicação somente em tempo de execução podem continuar a receber argumentos de tempo de execução concretos, como ID do catálogo, local de saída do Athena ou ID da conta Lake Formation, porque esses comandos operam após a renderização, não durante o planejamento semântico.

O renderizador emite:

• <target>.evidence.sql: notas de mapeamento de tabela não executável;
• <target>.evidence_ddl.sql: Iceberg DDL para tabelas de evidências canônicas, como ctrl_ingestion_runs, ctrl_ingestion_quality, ctrl_ingestion_errors e tabelas de governança/custo/linhagem;
• <target>.state_ddl.sql: Iceberg DDL para tabelas de estados canônicos como ctrl_ingestion_state e ctrl_ingestion_locks.

Os nomes das colunas da tabela de controle principal, como delta_version_before, delta_version_after e last_delta_version, são preservados para paridade. AWS preenche suas substituições neutras com identificadores de instantâneo Iceberg quando aplicável ou deixa os campos legados nulos com o marcador de versão da plataforma em operation_metrics_json.

Initial Artifact Types

O renderizador emite:

• <target>.review.md: status de planejamento, avisos, bloqueadores e mapeamento esperado do AWS;
• <target>.deployment_manifest.json: manifesto determinístico sobre os artefatos AWS gerados, incluindo categorias de artefatos, ordem de aplicação, limites de revisão e nomes auxiliares de tempo de execução opcionais;
• <target>.capabilities.json: a declaração de capacidade do adaptador usada para planejamento, incluindo metadados de suporte de origem AWS;
• <target>.evidence.sql: notas de mapeamento da tabela de evidências;
• <target>.evidence_ddl.sql: Iceberg DDL para evidências canônicas/tabelas de controle;
• <target>.state_ddl.sql: Iceberg DDL para tabelas de estado/bloqueio;
• <target>.cost.sql: relatório de custos operacionais somente consulta sobre ctrl_ingestion_runs e ctrl_ingestion_cost;
• <target>.iam_policy.json: revise o modelo de política IAM para a função de trabalho Glue gerada, incluindo Catálogo Glue, CloudWatch Logs, S3, Secrets Manager e permissões RDS IAM quando necessário;
• <target>.write_mode_review.md: lista de verificação de revisão específica para modos de gravação necessários para revisão, como historical e snapshot_reconcile_soft_delete;
• <target>.annotations.json: Glue Plano de atualização de anotação de catálogo para descrições de tabelas, parâmetros de tabelas, comentários de colunas e parâmetros de colunas, quando annotations é declarado;
• <target>.annotations_evidence.sql: inserções de evidências canônicas ctrl_ingestion_annotations para o plano de anotação;
• <target>.operations.json: metadados de operações normalizadas, quando operations é declarado;
• <target>.operations.sql: inserção de evidência canônica ctrl_ingestion_operations para metadados de operações;
• <target>.native_passthrough.json: plano de transferência de serviço nativo AWS para source.type: native_passthrough, quando declarado;
• <target>.lakeformation_evidence.sql: inserções de evidências de governança para concessões Lake Formation e estruturas de filtro de dados exigidas por revisão, quando access é declarado;
• <target>.performance_profile.json: lista de verificação de benchmark para mapeamentos sensíveis ao tempo de execução, como hash_diff_upsert;
• runtime/contractforge_aws_runner.py: executor Glue estável usado por implantações padrão;
• <target>.glue_job.py: script Glue Spark/Iceberg gerado para append, overwrite, upsert, hash_diff_upsert e trabalhos de streaming disponíveis agora com suporte;
• <target>.glue_job_definition.json: AWS Glue determinístico cria/atualiza carga útil para o script gerado, incluindo argumentos Iceberg, ativação de marcadores e dicas de dependência;
• <target>.cloudformation.json: scaffold CloudFormation parametrizado para o job Glue e bancos de dados Glue;
• <target>.terraform.tf: scaffold Terraform parametrizado para o trabalho Glue e bancos de dados Glue;
• <target>.glue_job.todo.md: explicação para modos planejados, mas ainda não renderizáveis.

A execução do tempo de execução pertence ao adaptador e é opcional. AWS Os auxiliares de envio do API são disponível atrás de contractforge-aws[runtime]; o trabalho Glue padrão aponta para o executor de biblioteca estável e passa o contrato publicado URI. Gerado Os scripts Glue permanecem apenas como artefatos de revisão e validação de sintaxe. AWS Glue a implantação sempre aponta para runtime/contractforge_aws_runner.py; o O modo de tempo de execução generated_script não é suportado intencionalmente. Scripts gerados eles próprios permanecem como código Glue/Spark simples e não contêm chamadas boto3.

Auxiliares de tempo de execução opcionais

O pacote do adaptador base permanece importável sem dependências AWS SDK. Os auxiliares de tempo de execução que chamam AWS APIs residem em contractforge_aws.runtime e exigem:

• um objeto cliente AWS fornecido pelo chamador; ou
• contractforge-aws[runtime], que instala boto3 e botocore.

Os primeiros auxiliares de tempo de execução publicam artefatos renderizados no S3, registram/atualizam definições de trabalho Glue, iniciam execuções de trabalho Glue, inspecionam status, mapeiam metadados Glue JobRun em registros de evidências principais e renderizam declarações INSERT de evidências explícitas de Iceberg:

from contractforge_aws import render_aws_deployment_manifest

manifest_json = render_aws_deployment_manifest(contract)

from contractforge_aws import render_aws_glue_job_definition

payload_json = render_aws_glue_job_definition(contract)

from contractforge_aws import render_aws_glue_job_cloudformation

template_json = render_aws_glue_job_cloudformation(contract)

from contractforge_aws import render_aws_glue_job_terraform

terraform_hcl = render_aws_glue_job_terraform(contract)

from contractforge_aws import publish_aws_contract_artifacts_to_s3

publish_aws_contract_artifacts_to_s3(contract, bucket="contractforge-artifacts", prefix="dev/orders")

Se environment.artifacts.uri for declarado, os chamadores poderão omitir bucket e prefix; o adaptador os resolve a partir do ambiente.

from contractforge_aws import deploy_aws_contract_to_glue

deployment = deploy_aws_contract_to_glue(contract, environment=environment_contract)

deploy_aws_contract_to_glue é o caminho AWS composto: renderizar, publicar em S3, materialize a definição de tarefa Glue com URIs de artefato final e, em seguida, crie ou atualize o trabalho Glue. É uma implantação de propriedade do adaptador, não uma execução central.

from contractforge_aws import register_aws_glue_job

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,
)

from contractforge_aws import register_aws_glue_job_definition_payload

registered = register_aws_glue_job_definition_payload(job_payload, glue_client=my_glue_client)

from contractforge_aws import apply_aws_lake_formation_contract

result = apply_aws_lake_formation_contract(contract, lakeformation_client=my_lf_client)

from contractforge_aws import apply_aws_annotations_contract

result = apply_aws_annotations_contract(contract, glue_client=my_glue_client)

from contractforge_aws import record_aws_operations_contract

result = record_aws_operations_contract(runner=my_sql_runner, contract=contract, run_id="run-123")

from contractforge_aws import ensure_aws_evidence_tables

result = ensure_aws_evidence_tables(
    runner=my_sql_runner,
    database="contractforge_ops",
    dialect="athena",
    warehouse_uri="s3://contractforge-lakehouse/evidence/",
)

from contractforge_aws import AthenaSqlRunner

runner = AthenaSqlRunner(database="contractforge_ops", output_location="s3://query-results/")

from contractforge_aws import get_aws_glue_job_run_status, start_aws_glue_job_run

run = start_aws_glue_job_run(job_name="cf-orders", arguments={"--contractforge-run-id": "run-123"})
status = get_aws_glue_job_run_status(job_name="cf-orders", run_id=run.run_id)

from contractforge_aws import wait_aws_glue_job_run

status = wait_aws_glue_job_run(job_name="cf-orders", run_id=run.run_id)

from contractforge_aws import reconcile_aws_glue_job_run_evidence

evidence = reconcile_aws_glue_job_run_evidence(
    job_name="cf-orders",
    run_id=run.run_id,
    target_table="glue.bronze.orders",
    mode="append",
)

from contractforge_aws import render_aws_glue_job_run_evidence_sql

sql = render_aws_glue_job_run_evidence_sql(
    job_name="cf-orders",
    run_id=run.run_id,
    target_table="glue.bronze.orders",
    mode="append",
    database="contractforge_ops",
)

Deliberadamente, esta ainda não é uma orquestração completa do ContractForge. Ele organiza a revisão artefatos, DDL, scripts Glue gerados, instantâneos de contrato de tempo de execução e o runner de biblioteca estável; registra a definição de trabalho com uma função IAM explícita e script URI; pode acionar/verificar uma execução Glue; e pode converter Glue JobRun campos como StartedOn, CompletedOn, JobRunState, ExecutionTime e DPUSeconds em objetos de registro de evidências principais. Os trabalhos Glue persistem em sua própria execução e evidências de qualidade para tabelas de controle Iceberg para caminhos de tempo de execução suportados; o auxiliares de reconciliação pós-execução permanecem auxiliares de revisão/aplicação explícitos para provas suplementares de execução e custo.

O registro do trabalho Glue pode ser conduzido por parâmetros explícitos ou pela carga útil .glue_job_definition.json renderizada. O auxiliar de carga útil remove campos somente de revisão, como contractforge_review_notes, antes de chamar Glue e valida o local do script Name, Role e S3 necessário.

A espera de execução do Glue é um auxiliar de pesquisa fino do GetJobRun. Ele retorna o GlueJobRunStatus final para execuções de SUCCEEDED e aumenta para estados de terminal com falha, como FAILED, STOPPED, TIMEOUT ou ERROR. Ele não tenta novamente, reinicia ou reconcilia evidências automaticamente.

Os auxiliares de tempo de execução Lake Formation preservam o limite de revisão. As concessões de tabela podem ser aplicadas a partir do plano renderizado. Os filtros de células de dados são ignorados por padrão e exigem allow_data_cells_filters=True mais um AWS account_id concreto, porque a semântica do filtro de linha e da máscara de coluna ainda exige revisão antes de ser confiável.

Glue Os auxiliares de anotação de catálogo preservam a definição da tabela atual antes de chamar UpdateTable. Eles leem GetTable, aplicam apenas descrições de tabela planejadas, parâmetros de tabela, comentários de coluna e parâmetros de coluna e enviam um TableInput completo para que os descritores de armazenamento, chaves de partição e parâmetros existentes sejam retidos.

Os auxiliares de operações usam um executor SQL de propriedade do chamador para inserir os metadados de operações normalizadas na tabela de evidências canônica ctrl_ingestion_operations. O auxiliar relata RECORDED, FAILED ou NOT_CONFIGURED e não possui agendamento ou ciclo de vida do mecanismo de consulta.

Os auxiliares de configuração de evidências usam um executor SQL de propriedade do chamador para aplicar o mesmo Iceberg DDL renderizado a partir do esquema de evidência principal. Eles podem criar tabelas de evidências e tabelas de estado fora de uma tarefa Glue gerada, preservando o limite do adaptador. Como o DDL é solicitado, a configuração da evidência requer um executor SQL em espera; o envio assíncrono é reservado para auxiliares de instrução única, como gravação de operações.

Quando o executor é Athena, a configuração de evidências usa Iceberg DDL nativo de Athena e requer um S3 warehouse_uri explícito para locais de tabela. Trabalhos Glue gerados continue a usar Spark Iceberg DDL com glue_catalog porque esse catálogo é um Catálogo de tempo de execução Spark, não um nome de catálogo do Athena.

A configuração de evidências do Athena usa o formulário Iceberg não CTAS do Athena: CREATE TABLE... [PARTITIONED POR (...)] LOCATION... TBLPROPERTIES ('table_type'='ICEBERG', 'formato'='parquet'). Ele cai intencionalmente Restrições de coluna somente Spark, como NOT NULL da configuração DDL enquanto preservando os nomes e tipos das colunas de evidências canônicas. Evidência de tempo de execução os registros ainda seguem contractforge_core.evidence; o adaptador só muda o dialeto de criação de tabela.

AthenaSqlRunner é um runner de conveniência opcional para essas superfícies auxiliares SQL. Ele chama o Athena somente quando instanciado e usado explicitamente, oferece suporte a clientes fornecidos pelo chamador para testabilidade/propriedade da sessão e pode aguardar o estado de consulta do terminal ou enviar sem esperar.

Os artefatos de passagem nativos preservam o mesmo limite. Eles classificam os prováveis ​​caminhos de serviço AWS:

• Amazon AppFlow para extração de SaaS gerenciada quando o aplicativo/objeto e o modelo de gatilho são compatíveis;
• AWS DMS para carregamento total do banco de dados ou replicação CDC quando JDBC portátil é insuficiente;
• AWS Glue conectores nativos, personalizados ou de parceiros para APIs proprietários ou extração de propriedade do conector.

O artefato renderizado inclui recommended_aws_paths, review_only_apply_candidates, review_required_inputs, contract_mapping, evidence_strategy e unsupported_claims. review_only_apply_candidates usa esqueletos em formato AWS API para appflow:CreateFlow, dms:CreateReplicationConfig e glue:CreateConnection para que os revisores possam ver o limite nativo pretendido, mas não chama APIs do conector AppFlow, DMS ou Glue.

Known Limitations

• Nenhuma chamada AWS SDK no pacote do adaptador base.
• Lake Formation data cell filters require explicit reviewed opt-in before application.
• Terraform e CloudFormation são emitidos como estruturas de revisão, não aplicadas automaticamente.
• Nenhuma reconciliação completa da tabela de controle pós-execução de propriedade do orquestrador nos primeiros auxiliares de tempo de execução; Os trabalhos Glue gerados persistem com suporte de execução, qualidade, esquema, estado, metadados, fluxo e evidências de linhagem no trabalho.
• Nenhuma execução sem servidor EMR nos primeiros auxiliares de tempo de execução.
• Nenhuma execução nativa de AppFlow/DMS na primeira fase do adaptador.
• A passagem nativa é renderizada apenas como transferência de revisão/aplicação; ele não chama APIs do conector AppFlow, DMS ou Glue automaticamente.
• A exclusão reversível de histórico e de instantâneo é necessária para revisão até que testes reais de Glue/Iceberg comprovem a semântica e o desempenho.

Evolução Futura do Núcleo

AWS provavelmente precisará de um modelo de capacidade mais rico ao longo do tempo:

• subtarget metadata;
• status por recurso em vez de booleanos;
• performance profiles;
• compatibilidade motor-consumidor para governança;
• selected incremental tracking strategy.

Não adicione essas abstrações até que o adaptador AWS comprove a necessidade por meio de testes e documentos.