A governança de catálogo e acesso também são contratos.

ContractForge separa os metadados da tabela do controle de acesso porque eles geralmente têm permissões, revisores e raio de explosão operacional diferentes.

Anotações

As anotações descrevem a tabela e seus campos. Eles podem ser aplicados depois que o destino existir e as falhas seguirem a política configurada.

YAML

# contracts/silver/s_customers.annotations.yaml
policy: warn
table:
  description: Current customer dimension.
  tags:
    domain: crm
    contains_pii: "true"

columns:
  email:
    description: Customer email address.
    pii:
      enabled: true
      type: email
      sensitivity: restricted

Python

from contractforge import ingest

result = ingest(
    source_table="main.crm_raw.customers",
    target_catalog="main",
    target_schema="crm_curated",
    target_table="s_customers",
    mode="hash_diff_upsert",
    hash_keys=["customer_id"],
    annotations={
        "policy": "warn",
        "table": {
            "description": "Current customer dimension.",
            "tags": {"domain": "crm", "contains_pii": "true"},
        },
        "columns": {
            "email": {
                "description": "Customer email address.",
                "pii": {
                    "enabled": True,
                    "type": "email",
                    "sensitivity": "restricted",
                },
            },
        },
    },
)

Metadados de operações

Os contratos de operações alimentam painéis e sistemas de alerta sem acoplar a biblioteca ao Slack, Teams, PagerDuty ou outro provedor de notificação.

YAML

# contracts/silver/s_customers.operations.yaml
operations:
  business_owner: sales-ops
  technical_owner: data-engineering
  support_group: data-platform
  criticality: high
  expected_frequency: daily
  freshness_sla_minutes: 180
  runbook_url: https://example.com/runbooks/customers

Python

from contractforge import ingest

result = ingest(
    source_table="main.crm_raw.customers",
    target_catalog="main",
    target_schema="crm_curated",
    target_table="s_customers",
    mode="hash_diff_upsert",
    hash_keys=["customer_id"],
    operations={
        "business_owner": "sales-ops",
        "technical_owner": "data-engineering",
        "support_group": "data-platform",
        "criticality": "high",
        "expected_frequency": "daily",
        "freshness_sla_minutes": 180,
        "runbook_url": "https://example.com/runbooks/customers",
    },
)

O acesso é adiado por design

A ingestão normal não deve exigir privilégios de segurança elevados. Os contratos de acesso são validados e aplicados através de comandos dedicados.

contractforge validate-access contracts/silver/s_customers
contractforge governance-check contracts/silver/s_customers
contractforge apply-access contracts/silver/s_customers

Por que isso é importante

Um gravador de dados pode carregar uma tabela sem se tornar o principal responsável por concessões, filtros de linha ou máscaras de coluna.

O *.ingestion.yaml correspondente define o target do bundle. Arquivos complementares de governança normalmente omitem target; quando declaram target, ele é usado apenas como verificação de compatibilidade com a ingestão.

Comportamento político

As falhas de governança são operacionalmente diferentes das falhas de gravação. A política controla se os metadados/desvios de acesso devem bloquear o fluxo de trabalho, serem registrados como evidência de alerta ou serem ignorados intencionalmente.

Área	Política	Comportamento	Quando usar
Anotações	warn	Tentativa de aplicar comentários/tags; gravar avisos sem falhar na gravação dos dados.	Padrão para implementação gradual e permissões mistas.
Anotações	fail	Falha no resultado da ingestão se as anotações não puderem ser aplicadas.	Use quando os metadados do catálogo fizerem parte do contrato de lançamento.
Anotações	ignore	Ignorar aplicativo de anotação.	Use para ambientes sem permissões de catálogo.
Acesso	validate_only	Valide o contrato de acesso e registre evidências de visualização/desvio sem aplicar alterações.	Solicitações pull, CI e fluxos de trabalho de separação de funções.
Acesso	apply	Aplique concessões, filtros e máscaras através de um fluxo de trabalho privilegiado.	Trabalhos de implantação pertencentes a uma entidade de segurança.
Acesso	ignore	Ignore as verificações de acesso e a aplicação.	Desenvolvimento local ou ambientes que não sejam do Unity-Catalog.

Ciclo de vida da governança

1. Valide o pacote. Verifique se as anotações, operações e regras de acesso fazem referência aos campos que existem no destino de ingestão.
2. Executar a ingestão. Os dados são gravados primeiro para que a tabela e as colunas existam fisicamente.
3. Aplicar anotações e operações. Comentários, tags e registros de propriedade são aplicados e registrados.
4. Aplique o acesso separadamente. As alterações de segurança são visualizadas, validadas e executadas por meio do fluxo de trabalho de acesso dedicado.

PII como anotação, não transformação

A classificação PII descreve os dados. Ele não deve mascarar ou alterar valores automaticamente durante a ingestão. O mascaramento pertence às políticas de acesso ao catálogo ou às funções de segurança downstream.

YAML

# In *.annotations.yaml
columns:
  national_id:
    description: Government-issued identifier.
    pii:
      enabled: true
      type: national_id
      sensitivity: confidential
    tags:
      retention_policy: restricted
      masking_candidate: "true"

Python

annotations = {
    "columns": {
        "national_id": {
            "description": "Government-issued identifier.",
            "pii": {
                "enabled": True,
                "type": "national_id",
                "sensitivity": "confidential",
            },
            "tags": {
                "retention_policy": "restricted",
                "masking_candidate": "true",
            },
        },
    },
}

Tabelas de desvio e auditoria

As ações de governança são escritas em tabelas de controle para que as equipes possam responder quais metadados foram aplicados, o que falhou e o que foi adiado intencionalmente.

Mesa	Usar
ctrl_ingestion_annotations	Anotações de tabela/coluna aplicadas, avisadas, ignoradas ou com falha.
ctrl_ingestion_operations	Propriedade, criticidade, SLA e instantâneos de metadados de suporte.
ctrl_ingestion_access	Acesse evidências de validação/aplicação, incluindo status de desvio.

Consultas úteis de governança

Tabelas com anotações PII

SELECT
  target_table,
  column_name,
  key,
  value,
  status,
  annotation_ts_utc
FROM main.ops.ctrl_ingestion_annotations
WHERE annotation_type = 'pii'
ORDER BY annotation_ts_utc DESC;

Acesse ações que exigem acompanhamento

SELECT
  target_table,
  access_type,
  principal,
  privilege,
  column_name,
  function_name,
  status,
  error_message,
  access_ts_utc
FROM main.ops.ctrl_ingestion_access
WHERE status <> 'APPLIED'
ORDER BY access_ts_utc DESC;