Capacidade Snowflake e paridade de evidências

Propósito

Esta especificação define como um futuro adaptador contractforge-snowflake deve mapear ContractForge Parâmetros principais do contrato e campos de evidência/tabela de controle para Recursos nativos do Snowflake.

O objetivo não é tornar o núcleo consciente do Snowflake. O objetivo é dar ao Adaptador Snowflake um alvo de implementação pesquisado:

Semântica do contrato ContractForge
  -> declaração de capacidade Snowflake
  -> implementação Snowflake SQL / task / stream / policy
  -> tabelas de evidência canônicas ContractForge preenchidas com valores Snowflake

As fontes deste documento são a documentação oficial do Snowflake. O adaptador deve verificar o comportamento em uma conta Snowflake real antes de alterar qualquer item REVIEW_REQUIRED para SUPPORTED.

Superfícies Snowflake de referência

Superfície Snowflake	Uso de ContractForge
SQL warehouse	Tempo de execução primário para tabela, SQL, arquivo preparado e ingestão baseada em mesclagem.
Banco de dados e esquema	Mapeamento para target.catalog e target.schema.
Tabelas, visualizações e estágios	Mapeamento para origens de tabelas governadas e origens de arquivos preparados.
COPY INTO <table>	Carregamento de arquivo temporário limitado e validação de carga.
Snowpipe	Carregamento de arquivos em etapas contínuo ou quase contínuo quando o contrato solicita a descoberta de arquivos além de simples carregamentos em lote.
Streams	Captura de dados alterados em tabelas e visualizações Snowflake.
Tasks	Execução agendada, gráficos de tarefas e jobs acionados por fluxo.
Políticas de acesso de linha	Implementação de filtro de linha.
Políticas de mascaramento	Implementação de máscara de coluna.
Tags de objeto e comentários	Implementação de metadados de anotação e governança.
Esquema de uso e informações da conta	Fonte de evidências nativas para consultas, tarefas, cargas de cópia, custos, políticas, tags e metadados de objetos.
Data Metric Functions	Superfície métrica de qualidade nativa opcional.

Referências principais:

• QUERY_HISTORY
• TASK_HISTORY
• QUERY_ATTRIBUTION_HISTORY
• COPY_HISTORY
• Tabela COPY INTO
• Snowpipe
• Streams
• CREATE TASK
• MERGE
• Esquema de informações COLUMNS
• Funções métricas de dados
• CREATE ROW ACCESS POLICY
• Column-level security / masking policies
• CREATE MASKING POLICY
• TAG_REFERENCES
• POLICY_REFERENCES
• ACCESS_HISTORY

Sub-alvos do adaptador

O adaptador Snowflake não deve declarar um recurso vago de snowflake. Isto deve declarar subalvos explícitos.

Subalvo	Status alvo	Propósito
snowflake_sql_warehouse	Primário	Execução de SQL na computação do warehouse. Lida com gravações de tabela, SQL, estágio de arquivo, qualidade, mesclagem e evidências.
snowflake_task_graph	Caminho de implantação principal	Renderiza artefatos de implantação de tarefas/gráficos de tarefas para execução agendada de projetos.
snowflake_snowpipe	Revisão primeiro	Lida com o carregamento contínuo de arquivos preparados onde a semântica do Snowpipe preserva o contrato.
snowflake_streams_tasks	Revisão primeiro	Lida com a tabela CDC e fluxos de trabalho incrementais tabela a tabela.
snowflake_snowpark	Futuro	Lida com transformações complexas ou comportamento do conector que não é limpo apenas no SQL.
snowflake_native_passthrough	Futuro	Delega para conectores nativos Snowflake ou ingestão de aplicativos nativos/de mercado.

Paridade de parâmetros principais

Sources

ContractForge parameter	Snowflake mapping	Status	Notes
source.type: table	SELECT ... FROM <database>.<schema>.<table>	SUPPORTED	O adaptador resolve referências lógicas para nomes totalmente qualificados.
source.type: view	SELECT ... FROM <database>.<schema>.<view>	SUPPORTED	O comportamento de visualização segura deve ser registrado nos detalhes do planejamento, quando relevante.
source.type: sql	Snowflake SQL query	SUPPORTED_WITH_WARNINGS	O dialeto SQL é específico do Snowflake. Os espaços reservados {{ table_ref:* }} portáteis permanecem resolvidos pelo adaptador.
source.type: staged_files com format: csv/json/parquet	Estágio interno/externo nomeado mais formato de arquivo nomeado ou formato de arquivo padrão do estágio, lido por meio de uma consulta preparada	SUPPORTED_WITH_WARNINGS	A projeção posicional CSV, a carga útil/projeção JSON VARIANT e a projeção Parquet são implementadas. Outros formatos continuam a ser necessários para revisão.
source.type: csv/json/parquet/orc/avro/xml/text	Normalize para staged_files ou revise a abreviação específica da fonte	REVIEW_REQUIRED	O adaptador aceita staged_files explícito primeiro para que o formato do arquivo, o estágio e os limites das evidências fiquem visíveis.
source.type: object_storage	Estágio externo sobre S3, Azure ou GCS	SUPPORTED_WITH_WARNINGS	A integração de armazenamento, a propriedade do estágio e os privilégios de caminho são de propriedade do ambiente.
source.type: incremental_files	COPY_HISTORY, Snowpipe, tabela de diretório ou tabela de estado do adaptador	REVIEW_REQUIRED	Snowflake oferece superfícies relacionadas, mas exatamente uma vez, a semântica de ordenação e reprocessamento depende do caminho de carregamento escolhido.
source.type: delta	Tabela/integração externa ou padrão de estágio importado	REVIEW_REQUIRED	A semântica do Delta não é uma semântica de tabela nativa do Snowflake.
source.type: iceberg_table	Suporte Apache Iceberg gerenciado por Snowflake ou externo	SUPPORTED_WITH_WARNINGS	Catálogo, suporte de gravação e comportamento de atualização de metadados devem ser declarados pelo adaptador.
source.type: http_file/http_csv/http_json/http_text	Integração de acesso externo, procedimento Snowpark ou caminho de arquivo pré-estágio	REVIEW_REQUIRED	O adaptador deve preferir arquivos pré-preparados para a primeira implementação.
source.type: jdbc/postgres/mysql/sqlserver/oracle/redshift/db2/mariadb	Função/procedimento externo, Snowpark ou padrão de conector nativo	REVIEW_REQUIRED	Snowflake não é um tempo de execução de extração geral do JDBC por padrão.
source.type: kafka_bounded	Snowpipe Streaming, estágio gerenciado por conector ou ponte de fluxo externo	REVIEW_REQUIRED	A semântica de repetição do Kafka difere da reprodução limitada do estilo Spark do ContractForge.
source.type: eventhubs_bounded	Ponte externa para stage Snowflake/Snowpipe Streaming	REVIEW_REQUIRED	A semântica de offset de evento entre nuvens exige revisão de desenho.
source.type: delta_share	Padrão de mercado/compartilhamento nativo/tabela externa	SUPPORTED_WITH_WARNINGS	Precisa de um resolvedor de origem específico do adaptador.
source.type: native_passthrough	Conector Snowflake/aplicativo nativo/fonte de mercado	SUPPORTED_WITH_WARNINGS	Deve retornar avisos explícitos sobre a semântica de propriedade do conector e lacunas de evidências.
source.connection_path	Conexão compartilhada resolvida pelo núcleo antes do planejamento do adaptador	SUPPORTED	O adaptador Snowflake recebe a origem resolvida; não deve reler caminhos locais arbitrários.
source.auth	Segredos Snowflake, integrações, autenticação de par de chaves ou resolvedor de segredo de ambiente	REVIEW_REQUIRED	O adaptador possui resolução de credenciais e deve redigir evidências.
source.watermark	Predicado SQL, deslocamento de fluxo, marcador COPY_HISTORY ou valor da tabela de estado	SUPPORTED_WITH_WARNINGS	O caminho de implementação altera a força das garantias.
source.progress_location	Tabela de estado ContractForge ou marcador de estágio/cópia	REVIEW_REQUIRED	O campo principal é portátil, mas a implementação do Snowflake deve escolher o estado da tabela versus os metadados nativos.
source.schema_tracking_location	Instantâneo do esquema de informações ou tabela de estado do adaptador	REVIEW_REQUIRED	Snowflake não precisa de um local de esquema no estilo Databricks; o adaptador deve mapear a intenção para a evidência do esquema.

Semântica de destino e gravação

ContractForge parameter	Snowflake mapping	Status	Notes
target.catalog	Database	SUPPORTED	Os nomes de catálogos lógicos devem ser resolvidos por meio de padrões de ambiente.
target.catalog_type	database / metastore classification	SUPPORTED	Usado para planejamento e diagnóstico; não é um parâmetro Snowflake DDL.
target.schema	Esquema	SUPPORTED	O comportamento de criação/validação é de propriedade do adaptador.
target.table	Mesa	SUPPORTED	Deve ser citado com segurança pelas regras de identificador Snowflake.
layer	Nomenclatura, comentários, tags e evidências	SUPPORTED	A camada são metadados ContractForge, não uma primitiva Snowflake.
mode: append	Anexo INSERT INTO... SELECT ou COPY INTO	SUPPORTED	Os carregamentos de arquivos devem persistir nos detalhes do COPY_HISTORY.
mode: overwrite	Padrão de substituição transacional, CREATE OR REPLACE TABLE AS SELECT ou truncar/inserir	SUPPORTED_WITH_WARNINGS	A atomicidade e a retenção de concessões dependem do padrão escolhido.
mode: upsert	MERGE INTO	SUPPORTED	Snowflake MERGE suporta cláusulas correspondentes e não correspondentes. O comportamento de origem duplicada deve ser pré-validado.
mode: hash_diff_upsert	Projeção de hash mais MERGE apenas para linhas alteradas	SUPPORTED_WITH_WARNINGS	A função hash, o tratamento nulo, o agrupamento e a conversão de tipo devem ser definidos e testados pelo adaptador.
mode: historical	SQL MERGE/padrão de transação, possivelmente com fluxos/tarefas	REVIEW_REQUIRED	Registros que chegam tarde, datação eficaz e tratamento de exclusão são semântica do projeto, e não uma única primitiva Snowflake.
mode: snapshot_reconcile_soft_delete	MERGE com design de origem correspondente/não correspondente	SUPPORTED_WITH_WARNINGS	Requer limite explícito de instantâneo e prova de integridade da origem.
schema_policy: strict	Compare o esquema de entrada com INFORMATION_SCHEMA.COLUMNS e falhe no desvio	SUPPORTED	O modo estrito não altera o esquema de destino.
schema_policy: additive_only	ALTER TABLE ADD COLUMN after nullable additive diff	SUPPORTED_WITH_WARNINGS	O mapeamento de tipo e as decisões de padrão/anulidade devem ser explícitas.
schema_policy: permissive	Plano DDL revisado	REVIEW_REQUIRED	A ampliação do tipo e as alterações incompatíveis exigem revisão.

Qualidade, Forma e Transformação

ContractForge parameter	Snowflake mapping	Status	Notes
quality_rules.not_null	SQL COUNT_IF(column IS NULL) ou DMF NULL_COUNT	SUPPORTED	O tempo de execução SQL é a primeira implementação; Os DMFs são uma integração de governação opcional.
quality_rules.required_columns	INFORMATION_SCHEMA.COLUMNS lookup	SUPPORTED	Colunas ausentes falham antes da gravação.
quality_rules.unique_key	Contagem duplicada agrupada SQL ou DMF DUPLICATE_COUNT	SUPPORTED	As chaves compostas devem usar o agrupamento SQL, a menos que o ajuste do DMF seja verificado.
quality_rules.accepted_values	SQL NOT IN ou DMF ACCEPTED_VALUES	SUPPORTED_WITH_WARNINGS	Conjuntos de valores grandes devem usar tabelas de referência em vez de listas embutidas.
quality_rules.min_rows	Contagem de linhas SQL ou DMF ROW_COUNT	SUPPORTED	O resultado vai para ctrl_ingestion_quality.
quality_rules.max_null_ratio	SQL null count divided by row count	SUPPORTED	O uso de DMF é opcional.
quality_rules.expressions	Snowflake SQL boolean predicate	SUPPORTED_WITH_WARNINGS	As expressões são específicas do dialeto e devem ser marcadas como tal no planejamento.
on_quality_fail: fail	Gerar erro antes do commit do alvo	SUPPORTED	A falha ainda deve persistir erro/executar evidências sempre que possível.
on_quality_fail: warn	Persistir evidências de qualidade e continuar	SUPPORTED	O status de execução permanece independente do status de qualidade.
on_quality_fail: quarantine	Grave linhas com falha em ctrl_ingestion_quarantine e, em seguida, grave linhas passadas	SUPPORTED_WITH_WARNINGS	A quarentena em nível de linha é suportada para regras SQL identificáveis ​​por linha; regras agregadas tornam-se avisos registrados.
shape	SQL sobre VARIANT, FLATTEN, conversões ou Snowpark	REVIEW_REQUIRED	JSON aninhado e explosão de matriz podem ser mapeados, mas a paridade com o comportamento da forma Spark/Glue deve ser testada.
transform.cast	Snowflake CAST / TRY_CAST depending strictness	SUPPORTED_WITH_WARNINGS	O comportamento do erro deve corresponder ao contrato.
transform.derive	SQL expression projection	SUPPORTED_WITH_WARNINGS	Revisão de dialeto necessária.
transform.standardize	SQL string functions	SUPPORTED	A normalização de corte, superior/inferior e espaço em branco são suficientemente portáteis.
transform.deduplicate	QUALIFY ROW_NUMBER() OVER (...) = 1	SUPPORTED_WITH_WARNINGS	A ordenação determinística é necessária.

Execução, Projeto e Implantação

ContractForge parameter	Snowflake mapping	Status	Notes
project.schedule.cron	CREATE TASK ... SCHEDULE = 'USING CRON <expr> <timezone>'	SUPPORTED	O cron da tarefa Snowflake inclui o fuso horário na sequência de agendamento.
project.schedule.timezone	Task cron timezone	SUPPORTED	O comportamento do fuso horário é específico da tarefa e não segue alterações posteriores de fuso horário da sessão.
project.depends_on	Task graph AFTER <task>	SUPPORTED_WITH_WARNINGS	A propagação de salto/falha do gráfico de tarefas deve ser capturada nos documentos de implantação.
execution.freshness	Agendamento de tarefas, tarefa acionada por fluxo, Snowpipe ou agendador externo	SUPPORTED_WITH_WARNINGS	Frescor é intenção; a aplicação depende do caminho do tempo de execução.
execution.latency_target	Preservado no plano/evidência e, opcionalmente, na tarefa/design do Snowpipe	SUPPORTED	Não é uma garantia de tempo de execução difícil por si só.
execution.preferred	Agendada, gráfico de tarefas, tarefa acionada por fluxo, Snowpipe ou orquestração externa	REVIEW_REQUIRED	O adaptador deverá ser bloqueado se o modo preferencial não puder preservar a semântica e nenhum substituto for declarado.
execution.fallback	Alternative implementation path	SUPPORTED	O planejador pode usar o substituto somente quando explicitamente permitido.
environment.artifacts.uri	Caminho do estágio, saída local, caminho do artefato Git ou armazenamento de objeto URI	SUPPORTED_WITH_WARNINGS	O adaptador Snowflake deve definir esquemas de artefatos aceitos.
environment.evidence	Banco de dados/esquema de evidências Snowflake	SUPPORTED	Os nomes das tabelas de evidências permanecem canônicos ctrl_ingestion_*.
environment.parameters.snowflake.warehouse	Warehouse binding	PLATFORM_EXTENSION	Configuração de implantação/tempo de execução de propriedade do adaptador.
environment.parameters.snowflake.role	Role binding	PLATFORM_EXTENSION	Configuração de segurança de propriedade do adaptador.
environment.parameters.snowflake.task_schema	Namespace de implantação de tarefa	PLATFORM_EXTENSION	Fique longe de contratos de ingestão.

Anotações e acesso

ContractForge parameter	Snowflake mapping	Status	Notes
annotations.table.description	COMMENT ON TABLE	SUPPORTED	A evidência deve registrar o SQL/id de consulta aplicado.
annotations.columns.*.description	COMMENT ON COLUMN	SUPPORTED	As evidências devem registrar o status por coluna.
annotations.*.tags	Snowflake object tags	SUPPORTED_WITH_WARNINGS	A criação de tags, namespace e valores permitidos são decisões de ambiente/governança.
annotations.*.pii	Tags e recomendação de política de mascaramento opcional	SUPPORTED_WITH_WARNINGS	As tags PII não impõem mascaramento automaticamente, a menos que o contrato de acesso o declare.
access.grants	GRANT statements to roles/users	SUPPORTED_WITH_WARNINGS	O vocabulário de privilégios precisa de mapeamento de adaptador. A hierarquia de papéis pode criar desvios.
access.row_filters	Políticas de acesso de linha	SUPPORTED_WITH_WARNINGS	As políticas Snowflake retornam booleano e são aplicadas a tabelas/visualizações. A lógica específica do principal geralmente reside dentro da expressão da política.
access.column_masks	Masking policies	SUPPORTED_WITH_WARNINGS	A compatibilidade de assinatura/tipo de política deve ser verificada. Algumas combinações de políticas têm limites de plataforma.
access.access_policy.on_drift	Compare as concessões/políticas declaradas com o estado real	SUPPORTED_WITH_WARNINGS	Reconcile/revoke paths require explicit review due to role inheritance.
access.revoke_unmanaged	Plano de revogação	REVIEW_REQUIRED	Nunca use como padrão alterações de acesso destrutivas.

Estratégia de armazenamento de evidências

O adaptador Snowflake deve persistir evidências nas tabelas Snowflake com o mesmo nomes canônicos e colunas definidos por contractforge_core.evidence. Estes são Tabelas de evidências ContractForge, não visualizações de uso da conta Snowflake. Snowflake visualizações nativas fornecem valores; eles não substituem a evidência ContractForge modelo.

Recommended default:

environment:
  adapter: snowflake
  evidence:
    database: CONTRACTFORGE
    schema: CF_EVIDENCE

As tabelas de controle devem ser somente anexadas, exceto superfícies auxiliares de bloqueio/estado onde o O adaptador possui uma estratégia de simultaneidade claramente documentada.

Mapeamento de tabela de controle

ctrl_ingestion_runs

ContractForge field group	Fonte Snowflake
Run identity	ContractForge run_id; SnowflakeQUERY_HISTORY.query_id; as execuções de tarefas também podem registrar TASK_HISTORY.graph_run_group_id.
Job identity	Banco de dados/esquema/nome da tarefa de TASK_HISTORY; execuções manuais usam ponto de entrada de procedimento/consulta.
Timing	QUERY_HISTORY.start_time, QUERY_HISTORY.end_time, total_elapsed_time; agendas de tarefas usam TASK_HISTORY.scheduled_time e completed_time.
Status	QUERY_HISTORY.execution_status mais status de exceção do adaptador; status da tarefa de TASK_HISTORY.state.
Error	QUERY_HISTORY.error_code e error_message; detalhes da exceção do adaptador após a redação.
Row metrics	QUERY_HISTORY.rows_inserted, rows_updated, rows_deleted, rows_unloaded, rows_produced; rows_read, rows_written, rows_quarantined calculados pelo adaptador quando os contadores nativos são insuficientes.
Bytes/partition metrics	bytes_scanned, bytes_written, bytes_written_to_result, partitions_scanned, partitions_total, campos de derramamento/rede em operation_metrics_json.
Tempo de execução	Nome/tamanho do armazém, função/usuário, tag de consulta, ponto de entrada e CURRENT_VERSION() onde coletados.
Versão da tabela	Snowflake não possui versão de tabela de destino no estilo Delta/Iceberg para tabelas padrão; mantenha table_version_before e table_version_after nulos e armazene marcadores de consulta/transação em operation_metrics_json.

ctrl_ingestion_state

Campo ContractForge	Fonte Snowflake
watermark_column, watermark_value	Marca d'água de contrato e resultado da consulta de marca d'água alta pós-leitura.
last_success_at_utc, last_status, last_run_id	ContractForge run finalization.
last_rows_written	Métricas de linha do adaptador.
last_table_version	Nulo para tabelas padrão; marcador de deslocamento/cópia de fluxo pode ser armazenado em JSON.
last_watermark_candidate	Candidate max watermark before commit.
state_details_json	Marcador de nome/deslocamento de fluxo, marcador de arquivo COPY_HISTORY, nome de pipe Snowpipe ou metadados de tarefa.

As visualizações de uso da conta Snowflake podem ter latência. Estado que afeta a correção deve ser escrito pelo adaptador durante a execução, em vez de depender apenas de Account Usage reconciliation.

ctrl_ingestion_quality

ContractForge field	Fonte Snowflake
rule_name	Nome da regra do contrato ou nome DMF nativo.
status, severity, failed_count	Resultado da avaliação do adaptador SQL.
observed_value	Contagem/proporção/valor da verificação SQL ou função de métrica de dados.
details_json	Predicado SQL, nome DMF, ID de consulta, limites de amostra e classificação de dialeto.

As funções métricas de dados Snowflake são entradas de evidências úteis, mas não são um substituição completa para verificações de qualidade de tempo de execução ContractForge porque ContractForge deve suportar comportamento de falha/aviso/quarentena durante a ingestão.

ctrl_ingestion_quarantine

ContractForge field	Fonte Snowflake
record_payload	Carga útil OBJECT_CONSTRUCT(*)/TO_JSON da projeção de linha com falha.
record_ref	Chave de tabela de teste opcional, chave natural de destino ou referência de arquivo/linha.
reason, rule_name	Failed ContractForge row-level rule.
quarantined_at_utc	Carimbo de data e hora do adaptador na gravação em quarentena.

Falhas de qualidade agregadas não podem produzir quarentena em nível de linha sem um predicado de linha explícito. O adaptador deve registrá-los como avisos ou falhas, não invente linhas em quarentena.

ctrl_ingestion_errors

ContractForge field	Fonte Snowflake
error_type, error_class	Classificador de exceção do adaptador mais categoria de erro Snowflake quando disponível.
error_message	Erro do adaptador redigido mais QUERY_HISTORY.error_message.
stack_trace	Pilha de procedimento/Snowpark quando disponível; caso contrário, nulo.
query_id / runtime_context_json	QUERY_HISTORY.query_id, role, warehouse, task metadata.

ctrl_ingestion_schema_changes

ContractForge field	Fonte Snowflake
Esquema antes/depois	Instantâneos do esquema do adaptador de INFORMATION_SCHEMA.COLUMNS.
Applied DDL	Instrução ALTER TABLE/CREATE TABLE e QUERY_HISTORY.query_id.
Drift classification	Resultado da política do esquema principal: estrito/aditivo/permissivo.

ctrl_ingestion_streams

ContractForge field	Fonte Snowflake
Batch identity	ID de execução da tarefa, ID do grupo de execução do gráfico, nome do fluxo, nome do tubo Snowpipe ou marcador de lote de cópia.
Progresso da fonte	Stream offset state, COPY_HISTORY.file_name, last_load_time, pipe received time.
Metrics	Linhas carregadas, linhas analisadas, contagem de erros, tamanho do arquivo, métricas de tarefa/consulta.
Status	Status da tarefa/COPY/Snowpipe normalizado para o status ContractForge.

A semântica de streaming e de disponibilidade imediata deve permanecer REVIEW_REQUIRED até o o adaptador prova o comportamento do ponto de verificação/estado para cada família de origem.

ctrl_ingestion_lineage

ContractForge field	Fonte Snowflake
Input/output objects	ACCESS_HISTORY objetos diretos/base/modificados quando disponíveis.
Query identity	query_id, tag de consulta e carimbo de data/hora de execução.
Event payload	Matrizes de objetos ACCESS_HISTORY nativos mais referências de origem/destino ContractForge.

ACCESS_HISTORY é uma fonte de auditoria; o adaptador ainda deve emitir um Evento de linhagem ContractForge durante a execução para que os painéis não dependam apenas de Account Usage latency.

A execução em tempo de execução agora grava um estilo ContractForge/OpenLineage imediato Evento COMPLETE com ID de execução do contrato, referência de origem, tabela de destino, linha contagem e IDs de consulta Snowflake. A reconciliação nativa ACCESS_HISTORY continua sendo um caminho de uso da conta atrasado: ele investiga por QUERY_TAG run_id estruturado e retorna PENDING sem escrever linhas até que as linhas de linhagem nativa correspondentes sejam published.

ctrl_ingestion_annotations

ContractForge field	Fonte Snowflake
Descrições de tabela/coluna	Instruções COMMENT aplicadas e IDs de consulta.
Tags	Função de tabela TAG_REFERENCES ou visualização de uso da conta, além de SQL aplicado.
Status	Aplicado/validado/avisado/falho por anotação.

ctrl_ingestion_access

ContractForge field	Fonte Snowflake
Grants	Aplicadas instruções GRANT e verificações de esquema de informações/uso da conta.
Políticas de acesso de linha	Política de acesso de linha criada/aplicada DDL e POLICY_REFERENCES.
Masking policies	Política de mascaramento criada/aplicada DDL e POLICY_REFERENCES.
Drift status	Comparação do adaptador do contrato de acesso declarado e do estado atual do Snowflake.

ctrl_ingestion_operations

Os campos de operações vêm de ContractForge operations.yaml. Snowflake pode adicionar nome da tarefa, cronograma, armazém, integração de alertas e evidência de tag de consulta, mas não deve redefinir propriedade, criticidade ou semântica SLA.

ctrl_ingestion_explain

ContractForge field	Fonte Snowflake
plan_text	Saída EXPLAIN ou referência de perfil/relatório.
explain_format	TEXT ou JSON quando suportado pela instrução renderizada.
captured_at_utc	Carimbo de data/hora do adaptador.
details_json	Consultar id/perfil URL quando disponível.

A execução em tempo de execução captura EXPLAIN USING TEXT para a gravação renderizada instrução por padrão e armazena falhas como métricas de execução sem falhar no execução de ingestão. Os contratos podem desabilitar a captura com extensions.snowflake.explain_enabled: false.

ctrl_ingestion_cost

ContractForge field	Fonte Snowflake
signal_name	query_count, bytes_scanned, execution_time_ms, cloud_services_credits, rows_produced, warehouse_count, attributed_compute_credits, query_acceleration_credits, later snowpipe_bytes_billed.
signal_value	Totais QUERY_HISTORY, QUERY_ATTRIBUTION_HISTORY.credits_attributed_compute, contagens de metadados de armazém ou COPY_HISTORY.bytes_billed posterior para Snowpipe.
payload_json	ID/nome do armazém, ID da consulta, ID da consulta raiz, tag de consulta, créditos de serviços em nuvem, créditos de aceleração, bytes digitalizados/gravados e metadados de tarefas.

O custo é um sinal operacional, não uma reconciliação de faturamento. Uso da conta latência significa que a evidência de custo pode ser anexada por um comando de reconciliação posterior. Se o Uso da conta ainda não tiver produzido linhas correspondentes, a reconciliação reportará um status pendente sem inserir evidências duplicadas. O mesmo caminho pendente é usado quando a função de execução não consegue ler o uso da conta, com um aviso para operadores podem conceder a função de banco de dados Snowflake necessária separadamente do tempo de execução ingestion privileges.

ctrl_ingestion_metadata

O adaptador preenche os metadados do componente ContractForge, versão principal, adaptador versão, versão do esquema de controle, conta/região Snowflake quando configurada, padrões de warehouse/função e sinalizadores de recursos de tempo de execução. Valores sensíveis devem ser redacted.

Query Tag Requirement

O adaptador Snowflake deve definir um QUERY_TAG estruturado para cada instrução que ele possui. No mínimo:

{
  "product": "contractforge",
  "adapter": "snowflake",
  "run_id": "<contractforge-run-id>",
  "project": "<project-name>",
  "target": "<database.schema.table>"
}

Isso fornece QUERY_HISTORY, QUERY_ATTRIBUTION_HISTORY, ACCESS_HISTORY e tarefa de diagnóstico de uma chave de junção estável de volta à evidência ContractForge.

Revise os limites

O planejador Snowflake inicial deve retornar REVIEW_REQUIRED ou SUPPORTED_WITH_WARNINGS para estas áreas até ser comprovado por testes reais:

• incremental_files usando Snowpipe ou histórico de cópia.
• Kafka/Event Hubs bounded replay.
• histórico com linhas que chegam atrasadas, exclusões e janelas de validade sobrepostas.
• Exclusão reversível de instantâneo sem um instantâneo de origem completo comprovado.
• Políticas de acesso e mascaramento de linha com lógica específica do principal.
• Geração de políticas de mascaramento baseadas em tags.
• Operações shape complexas em cargas VARIANT aninhadas.
• Quarentena para regras de qualidade agregadas.
• Ampliação de tipo e alterações de esquema incompatíveis.
• Atribuição de custos quando a latência de uso da conta atrasa linhas de custo de consulta.

Alvo de Declaração de Capacidade Inicial

O primeiro conjunto de recursos do adaptador Snowflake deve ser conservador:

Area	Initial status
Fontes de tabela/visualização/sql	SUPPORTED
Staged file batch load	SUPPORTED_WITH_WARNINGS
Append	SUPPORTED
Overwrite	SUPPORTED_WITH_WARNINGS
upsert do estado atual	SUPPORTED
hash-diff upsert	SUPPORTED_WITH_WARNINGS
historical	REVIEW_REQUIRED
Snapshot soft delete	SUPPORTED_WITH_WARNINGS
Política de esquema estrita	SUPPORTED
Política de esquema aditivo	SUPPORTED_WITH_WARNINGS
Regras básicas de qualidade	SUPPORTED
Quarentena de qualidade	SUPPORTED_WITH_WARNINGS
Comentários de anotações	SUPPORTED
Tags	SUPPORTED_WITH_WARNINGS
Grants	SUPPORTED_WITH_WARNINGS
Políticas de acesso de linha	SUPPORTED_WITH_WARNINGS
Masking policies	SUPPORTED_WITH_WARNINGS
Scheduled projects	SUPPORTED
Task dependencies	SUPPORTED_WITH_WARNINGS
Evidência de custo	SUPPORTED_WITH_WARNINGS
Evidência de linhagem	SUPPORTED_WITH_WARNINGS

Testes de aceitação para um futuro adaptador

1. Planeje o projeto canônico do medalhão Supabase contra Snowflake e produza exact warnings/review items.
2. Renderize SQL para fontes de tabela, SQL e arquivos preparados sem importar um Cliente Snowflake no núcleo.
3. Execute acréscimo, substituição e atualização do estado atual em uma conta Snowflake real.
4. Verify ctrl_ingestion_runs, state, quality, quarantine, errors, schema_changes, annotations, access, lineage, operations, explain e as tabelas cost usam o esquema principal.
5. Join ContractForge run_id to Snowflake QUERY_HISTORY through QUERY_TAG.
6. Capture evidências de tarefas para um projeto agendado com pelo menos uma dependência.
7. Aplique comentários/tags e valide-os através do TAG_REFERENCES.
8. Aplique políticas de acesso e mascaramento de linha e valide-as por meio de POLICY_REFERENCES.
9. Prove que o histórico permanece REVIEW_REQUIRED até que o projeto declare o políticas de atraso, exclusão e data de vigência necessárias para uma execução segura.