Critérios de superfície estável Snowflake

Propósito

Este documento define as condições verificáveis ​​para o tratamento contractforge-snowflake como estável para seu suporte snowflake_sql_warehouse surface.

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 Snowflake. Diz que a superfície do armazém Snowflake SQL está documentada aqui passou no planejamento, renderização, publicação de estágio, tempo de execução do procedimento hospedado, evidências, auditoria, ciclo de vida e verificações de paridade sem contratos específicos workarounds.

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

Scope

A superfície Snowflake estável é:

• Snowflake Tempo de execução do armazém SQL;
• Tabelas nativas Snowflake;
• catalogação de banco de dados/esquema Snowflake;
• Evidência ContractForge como tabelas de controle Snowflake;
• executor de biblioteca de procedimentos Snowpark hospedado com importações ZIP preparadas;
• governança por meio de comentários, tags e ajudantes de validação/aplicação onde a equivalência for comprovada ou explicitamente necessária para revisão.

Famílias de origem estáveis:

• table e view;
• sql / query;
• staged_files com CSV, JSON e Parquet usando arquivo nomeado Snowflake formats.

Modos de gravação estáveis:

• append;
• overwrite;
• upsert;
• hash_diff_upsert como SUPPORTED_WITH_WARNINGS; a produção de referência o benchmark é validado e a evidência SLA específica da carga de trabalho ainda é necessária para novas reivindicações de produção.

Limites exigidos para revisão:

• Snowpipe, Streams, Snowpipe Streaming e ingestão do conector Kafka surfaces;
• Data Metric Functions integration;
• historical;
• snapshot_reconcile_soft_delete;
• política de acesso de linha ou mascaramento da aplicação da política em contas onde a política features are unavailable.

Inherited Preconditions

Esses invariantes de repositório devem passar antes que a estabilidade do Snowflake possa ser evaluated.

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 importação padrão Snowflake mantém os SDKs de tempo de execução opcionais	tests/test_snowflake_adapter.py
Os documentos e o relatório de status do Snowflake permanecem sincronizados	tests/test_snowflake_stability_docs.py
CI constrói a roda adaptadora Snowflake	Pacote .github/workflows/ci.yml/escopos completos

If any precondition fails, Snowflake 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 SQL gerado compilar portas passam para Snowflake.

Como verificar. Execute:

uv run pytest tests/test_snowflake_*.py tests/test_adapter_independence.py tests/test_publication_packaging.py tests/test_package_version.py
uv run contractforge-snowflake smoke --database CONTRACTFORGE_TEST --schema PUBLIC

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 somente comandos, sem tempo de execução manuscrito SQL fora do adaptador.

Projetos necessários:

• snowflake_smoke_minimal;
• snowflake_smoke_stage_publish;
• snowflake_smoke_procedure;
• snowflake_usgs_rest_medallion.

Cada projeto deve criar/gravar tabelas Snowflake 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 a smoke do Snowflake CLI e os fluxos do projeto:

contractforge-snowflake smoke --connect-options <connection.yaml> --execute --execute-cleanup
contractforge-snowflake smoke-stage-publish --connect-options <connection.yaml> --execute --execute-cleanup
contractforge-snowflake smoke-procedure --connect-options <connection.yaml> --execute --execute-cleanup

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:

• fonte ausente;
• aborto de qualidade;
• falha estrita de esquema;
• redaction of connection secrets in diagnostics.

Como verificar. Execute o smoke do caminho de falha Snowflake com a limpeza habilitada e auditar ctrl_ingestion_runs, ctrl_ingestion_errors e ctrl_ingestion_quality.

Status. met.

4. Auditoria de evidências

O que deve ser válido. As tabelas de controle canônico são escritas em Snowflake e auditadas as contagens correspondem aos resultados de smoke esperados.

Tabelas obrigatórias:

• ctrl_ingestion_runs;
• ctrl_ingestion_errors;
• ctrl_ingestion_quality;
• ctrl_ingestion_quarantine;
• ctrl_ingestion_schema_changes;
• ctrl_ingestion_state;
• ctrl_ingestion_annotations;
• ctrl_ingestion_access;
• ctrl_ingestion_operations;
• ctrl_ingestion_lineage;
• ctrl_ingestion_explain;
• ctrl_ingestion_cost.

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 Snowflake são limitadas à ligação da fonte, ambiente, namespace de tabela nativa, configurações de governança Snowflake e aceita revisar limites.

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/snowflake-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 clientes Snowflake.
• O pacote Snowflake base não importa antecipadamente o conector Snowflake ou Snowpark SDK modules.
• Os artefatos renderizados não contêm segredos de texto simples.
• As opções de conexão de tempo de execução estão na lista de permissões.
• Stage artifact paths reject unsafe traversal.
• Avisos de falha e reconciliação editam valores confidenciais antes da evidência gravações ou saída CLI.

Status. met.

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

A superfície suportada estável está pronta. stable_final é verdadeiro para o documentado reivindicação porque recursos mais amplos indisponíveis ou não implementados são explicitamente excluded:

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.
Políticas de acesso de linha e políticas de mascaramento	EXCLUDED_FROM_STABLE_FINAL	A conta conectada retorna Unsupported feature 'ROW ACCESS POLICY'; execute novamente e promova apenas em uma conta onde os recursos de política nativa estejam disponíveis.
Continuous ingestion	EXCLUDED_FROM_STABLE_FINAL	Snowpipe, Streams, Snowpipe Streaming e ingestão de conector Kafka exigem um mapeamento de conector/tempo de execução separado com semântica de recuperação e evidência.
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. São limites explícitos sobre o que o estábulo Snowflake surface claims.

Machine-Readable Gate

Usar:

contractforge-snowflake 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/snowflake-stable-surface-evidence.json.

Use --strict-final em fluxos de trabalho que devem impor o final estável documentado reivindicação e exclusões.