Versionamento de deploy

ContractForge registra deploys como evidência de primeira classe. Um deploy não é apenas um conjunto de arquivos copiados para uma plataforma; é um evento de control-plane versionado, com hashes estáveis para o contrato, o ambiente resolvido, o manifesto do adaptador e a linha de deploy.

O objetivo é repetibilidade. Uma equipe deve conseguir responder qual contrato foi implantado, qual pacote runtime o renderizou, qual artefato de plataforma foi criado e se um deploy posterior alterou a semântica ou apenas regenerou a mesma intenção.

Limite de responsabilidade

O core controla o contrato do ledger:

• schema ctrl_deployment_versions;
• regras determinísticas de hash;
• formato da linha de deploy;
• campos de identidade estáveis compartilhados entre adaptadores.

Os adaptadores controlam a persistência na plataforma:

• criação da tabela no destino;
• inserts e updates durante o deploy;
• referências para artefatos nativos;
• metadados dos pacotes runtime do adaptador.

O ledger nunca muda a semântica de ingestão. Ele registra o resultado de um comando de deploy.

Colunas do ledger

Coluna	Significado
deployment_id	Identificador único de um comando de deploy.
deployment_step_id	Identificador determinístico do passo dentro do deploy.
deployment_hash	Hash estável da linha de deploy, excluindo metadados mutáveis de resultado.
contract_hash	Hash estável do payload de contrato usado naquele passo.
environment_hash	Hash estável do ambiente resolvido.
manifest_hash	Hash estável do manifesto de deploy do adaptador.
adapter	Adaptador que renderizou ou implantou o artefato.
runtime_package_versions	Versões do core e do adaptador usadas pelo deploy.
artifact_uri	Referência nativa do artefato quando disponível.
status	Planejado, implantado, falho ou status terminal específico do adaptador.

Armazenamento nativo

Adaptador	Armazenamento do ledger
Databricks	Tabela Delta no catálogo/schema de evidência configurado.
AWS	Tabela Iceberg registrada no Glue Catalog.
Snowflake	Tabela SQL no database/schema de evidência configurado.
Fabric	Tabela Delta Lakehouse no schema de evidência configurado.
GCP	Tabela BigQuery no dataset de evidência configurado.

Semântica dos hashes

• contract_hash muda quando o payload efetivo do contrato muda.
• environment_hash muda quando o ambiente resolvido de deploy muda.
• manifest_hash muda quando instruções de deploy pertencentes ao adaptador mudam.
• deployment_hash muda quando a linha estável de deploy muda.

Campos mutáveis de runtime, como timestamps, detalhes de status terminal e ids de jobs de plataforma, não fazem parte do hash estável de deploy.

Uso operacional

• Mesmo contract hash, environment hash diferente: mesma intenção implantada em outro binding de destino.
• Mesmo contract hash e environment hash, manifest hash diferente: artefato de plataforma ou comportamento de deploy do adaptador mudou.
• Contract hash alterado: a semântica de ingestão mudou e deve passar por revisão normal de contrato.
• Status falho com hashes registrados: o deploy falho continua auditável.

Status da release atual

O versionamento de deploy faz parte do public technical preview atual. O schema e as regras de hash pertencem ao core, enquanto o armazenamento por adaptador continua nativo da plataforma e pode ganhar metadados específicos antes de um futuro congelamento de API 1.0.