Matriz de estabilização Snowflake

Propósito

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

O alvo é snowflake_sql_warehouse:

• Snowflake Tempo de execução do armazém SQL;
• Tabelas nativas Snowflake;
• catalogação de banco de dados/esquema Snowflake;
• governança opcional por meio de tags, comentários, políticas de acesso a linhas e políticas de mascaramento;
• As tabelas de evidências ContractForge persistiram como tabelas de controle Snowflake.

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

Escopo de estabilização

O escopo do candidato estável é intencionalmente menor que o Snowflake completo tese.

Área	Escopo de candidato estável	Fora do escopo para candidato estável
Origens	table, view, sql, staged_files com formatos de arquivo nomeados CSV, JSON e Parquet	autoloader, kafka, copy_into, Snowpipe, streams, stages externos
Modos de gravação	append, overwrite, upsert, hash_diff_upsert	equivalência histórica, soft delete por snapshot
Qualidade	abortar, avisar, quarentena em nível de linha, not_null, required_columns, accepted_values, min_rows, unique_key, max_null_ratio, expressões em nível de linha	Integração com Data Metric Functions
Preparação	Casts, derives, padronização, filtros e desduplicação determinística compatíveis com SQL	Formas aninhadas complexas, explosões de matrizes, operações inseguras de bronze
Política de esquema	Aditiva, estrita e permissiva via INFORMATION_SCHEMA.COLUMNS	Políticas automáticas de evolução de coluna
Evidência	execuções, erros, qualidade, quarentena, alterações de esquema, estado, anotações, acesso, operações, linhagem, explicação, custo	Armazenamentos de evidências alternativos
Governança	Comentários de tabela/coluna, tag SQL com modo somente validação, política de acesso de linha SQL, política de mascaramento SQL, controle de revogação destrutivo	Garantias automáticas do mecanismo do consumidor para filtros de linha e máscaras de coluna
Implantação	Validação de simulação, publicação no estágio, execução de procedimento hospedado, renderização de gráfico de tarefa, execução/limpeza de projeto	Execução do gráfico de tarefas ao vivo (bloqueada por concessões de tarefas)
Custo	Reconciliação de histórico de consultas, sinais de atribuição de consulta, tratamento de pendência/latência	Dashboards de custo em tempo real
Linhagem	Linhagem imediata e evidências explicativas, reconciliação atrasada de ACCESS_HISTORY	Streaming de linhagem em tempo real

Projetos de teste necessários

O adaptador Snowflake não pode ser estabilizado apenas com testes de renderização. Esses cenários executam comandos contractforge-snowflake contra uma conta Snowflake real.

Projeto	Fonte	Objetivo principal	Resultado obrigatório
smoke	Fontes de teste geradas	Ciclo completo de append, overwrite, quarentena, upsert e hash-diff	Cinco contratos concluídos com sucesso com evidências de controle correspondentes
smoke-failure-paths	Contratos ruins controlados	Evidência de erro, evidência de falha na execução, redação, fonte ausente, cancelamento de qualidade, esquema estrito	Falhas produzem evidências redigidas sem expor segredos
smoke-stage-publish	Stage interno	Publicação de stage, recarga de artefato, execução de contrato em stage	O pacote publicado é carregado e executado a partir do @stage
smoke-procedure	Stage interno + procedure	Implantação de procedure, importações de ZIP preparadas, chamada de procedure	A procedure implanta e executa um contrato
smoke-task-graph	Procedure + tasks	Implantação de gráfico de tasks, execução de task raiz, pesquisa de histórico de tasks	As tasks são implantadas e executadas por meio da procedure do executor

Os cenários hash-diff devem declarar merge_keys e uma estratégia de hash. O Snowflake o adaptador valida chaves de mesclagem nulas e duplicadas antes de executar a gravação. Hash a computação usa a função Snowflake do HASH em vez de não mesclado, não excluído colunas.

Portas de release

Porta	Requisito	Valores de status
Conjunto local G0	Testes de unidade e renderização aprovados	PASS, FAIL
Compilação de renderização G1	Contratos Smoke tornam Snowflake SQL válido sem erros de sintaxe	PASS, FAIL
Fluxo de publicação G2	Os artefatos são publicados no stage interno do Snowflake e recarregados corretamente	PASS, FAIL
Tempo de execução de sucesso do G3	Contratos Smoke são executados com sucesso por meio de executor apoiado por conector	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
Auditoria de controle G5	As tabelas de evidências correspondem às contagens e status esperados após a execução da smoke	PASS, FAIL
Linhagem G6	A linhagem imediata e a evidência explicativa são escritas; a reconciliação ACCESS_HISTORY lida com pendência/latência	PASS, FAIL
Custo G7	A reconciliação do histórico de consultas investiga tags de consulta estruturadas e registra sinais de custo	PASS, FAIL
Governança G8	Os comentários se aplicam corretamente; a tag somente evidência de validação corresponde às concessões esperadas	PASS, FAIL
Procedure G9	A procedure Snowpark é implantada e executada com importações de biblioteca ZIP preparadas	PASS, BLOCKED
Gráfico de tasks G10	As tasks são implantadas e executadas por meio da procedure do executor	PASS, FAIL
Paridade G11	As diferenças contratuais Snowflake/Databricks/AWS são documentadas e mínimas	PASS, REVIEW_REQUIRED, FAIL
Documentação G12	Os documentos, especificações e site do usuário Snowflake refletem o comportamento testado	PASS, FAIL
Ciclo de vida G13	Os objetos de teste de smoke têm um plano de limpeza não destrutivo e documentado	PASS, FAIL

O adaptador não é estável até que todas as portas não bloqueadas sejam PASS, exceto itens de paridade REVIEW_REQUIRED explicitamente aceitos. Portas bloqueadas exigem um plano de desbloqueio documentado.

Rastreador de estabilização

Item	Status atual	Observações
Testes de unidade do adaptador local Snowflake	PASS	Conjunto Snowflake focado: 175 aprovados. Conjunto completo: 1421 aprovados, 2 falhas conhecidas de AWS não relacionadas ao Snowflake.
Compilação de renderização de contrato de smoke	PASS	A simulação mínima de smoke validou todos os contratos e renderiza SQL sem erros de sintaxe.
Smoke de publicação em stage	PASS	smoke-stage-publish criou um stage interno temporário, publicou o pacote do executor de biblioteca, recarregou os artefatos do @stage e executou o contrato preparado.
Tempo de execução de sucesso mínimo	PASS	Todos os cinco contratos (anexar, substituir, colocar em quarentena, upsert, hash-diff) foram concluídos com êxito por meio de um executor apoiado por conector com evidências.
Tempo de execução do caminho de falha	PASS	Fonte ausente, interrupção de qualidade e falhas estritas de esquema produziram evidências de erro redigidas sem expor segredos de conexão.
Auditoria de tabela de controle	PASS	A verificação de smoke confirmou linhas de execução, erro, qualidade, quarentena, alteração de esquema, estado, anotação, acesso, operações, linhagem, explicação e evidência de custo.
Evidência de linhagem	PASS	A linhagem imediata gravou 5 linhas em ctrl_ingestion_lineage. EXPLAIN USING TEXT gravou 5 linhas em ctrl_ingestion_explain. A reconciliação ACCESS_HISTORY retornou PENDING com 0 linhas, correspondendo à latência de uso da conta.
Reconciliação de custo	PASS	A reconciliação do histórico de consultas investigou IDs de execução estruturados do QUERY_TAG e retornou PENDING para uso atrasado da conta. As tags de consulta de tempo de execução armazenam JSON analisáveis ​​com nomes de destino sem aspas.
Comentários e tags de governança	PASS	Comentários de tabela/coluna aplicados; marque evidências somente validadas registradas com concessões corretas.
Política de esquema	PASS	Inspeção INFORMATION_SCHEMA.COLUMNS com fallback de metadados do conector; smoke de coluna aditiva e smoke de falha estrita passaram.
Tempo de execução de qualidade	PASS	Todos os cenários de aprovação, quarentena e aborto produziram evidências corretas e propagaram quality_status em registros de execução.
Idempotência de estado e bloqueios	PASS	Cálculo de candidato de marca d'água, filtragem anterior de marca d'água, salto de repetição idempotente, aquisição de bloqueio e teste de liberação.
Implantação de procedimento	PASS	Procedimento Snowpark hospedado implantado com importações ZIP preparadas para as bibliotecas principais/adaptadores, chamado de executor estável, e o live smoke gravou 2 linhas.
Implantação do gráfico de tarefas	PASS	O Live Smoke implantou o gráfico, executou a tarefa root, aguardou o sucesso da tarefa root/dependente e limpou os artefatos do smoke.
Paridade de origem de arquivo preparada	PASS	Projeções posicionais CSV, projeções tipadas/carga útil JSON e projeções tipadas Parquet com formatos de arquivo nomeados validados. Caminhos inseguros e expressões de coluna rejeitados.
Preparation registry	PASS	Projeção de metadados, filtros, conversões, derivações, padronização e desduplicação determinística validada com smoke viva.
Registro do modo de gravação	PASS	Anexar, substituir, upsert e hash-diff divididos em módulos de registro independentes com validação de chave de mesclagem pré-gravada.
Cleanup lifecycle	PASS	smoke --execute --execute-cleanup removes all CF_SMOKE_* objects. cleanup-plan produces non-destructive DROP IF EXISTS SQL.
Docs/site update	PASS	O guia de operações do adaptador Snowflake, o plano de execução de paridade, as especificações de paridade de capacidade e a matriz de estabilização são publicados.

Plano de desbloqueio de portões bloqueados

A smoke da política de acesso Snowflake é bloqueada pela resposta do recurso da conta Unsupported feature 'ROW ACCESS POLICY'. Essa alegação de aplicação da política é explicitamente excluído do stable-final para contas onde a política nativa recursos não estão disponíveis. A ingestão contínua também está excluída stable-final até que um mapeamento de tempo de execução/evidência separado seja implementado. A semântica histórica/instantânea é excluída do final estável até a paridade existem evidências.

Machine-Readable Status

contractforge-snowflake stabilization-report

Para a versão atual, a classificação pretendida é STABLE_SUPPORTED_SURFACE com supported_surface_ready: true e stable_final: true. Ingestão contínua, política dependente de recursos da conta aplicação e exclusão reversível de histórico/instantâneo são excluídas do final estável, e o benchmark hash-diff de referência é validado.