Fase 4: Deduplicacao de Armazenamento

2026-02-15

Quando multiplas tesseras compartilham a mesma foto, o mesmo clipe de audio ou os mesmos dados de fragmento, a camada de armazenamento antiga mantinha copias separadas de cada. Em um no armazenando milhares de tesseras para a rede, essa duplicacao se acumula rapidamente. A Fase 4 continua com deduplicacao de armazenamento: um armazenamento enderecavel por conteudo (CAS) que garante que cada dado unico seja armazenado exatamente uma vez em disco, independentemente de quantas tesseras o referenciam.

O design e simples e comprovado: hash do conteudo com BLAKE3, usar o hash como nome do arquivo e manter uma contagem de referencias no SQLite. Quando duas tesseras incluem a mesma foto de 5 MB, um arquivo existe em disco com refcount 2. Quando uma tessera e deletada, o refcount cai para 1 e o arquivo permanece. Quando a ultima referencia e liberada, uma varredura periodica limpa o orfao.

O que foi construido

Migracao do esquema CAS (tesseras-storage/migrations/004_dedup.sql) — Tres novas tabelas:

cas_objects — rastreia cada objeto no armazenamento: hash BLAKE3 (chave primaria), tamanho em bytes, contagem de referencias e timestamp de criacao
blob_refs — mapeia identificadores logicos de blobs (hash da tessera + hash da memoria + nome do arquivo) para hashes CAS, substituindo a convencao antiga de caminhos no sistema de arquivos
fragment_refs — mapeia identificadores logicos de fragmentos (hash da tessera + indice do fragmento) para hashes CAS, substituindo o antigo layout do diretorio fragments/

Indices nas colunas de hash garantem lookups O(1) durante leituras e contagem de referencias.

CasStore (tesseras-storage/src/cas.rs) — O motor central de armazenamento enderecavel por conteudo. Arquivos sao armazenados sob um diretorio de prefixo de dois niveis: <raiz>/<prefixo-hex-2-chars>/<hash-completo>.blob. O armazenamento fornece cinco operacoes:

put(hash, data) — escreve dados em disco se ainda nao presente, incrementa o refcount. Retorna se ocorreu um hit de deduplicacao.
get(hash) — le dados do disco pelo hash
release(hash) — decrementa o refcount. Se chegar a zero, o arquivo em disco e deletado imediatamente.
contains(hash) — verifica existencia sem ler
ref_count(hash) — retorna a contagem de referencias atual

Todas as operacoes sao atomicas dentro de uma unica transacao SQLite. O refcount e a fonte de verdade — se o refcount diz que o objeto existe, o arquivo deve estar em disco.

FsBlobStore com CAS (tesseras-storage/src/blob.rs) — Reescrito para delegar todo armazenamento ao CAS. Quando um blob e escrito, seu hash BLAKE3 e computado e passado para cas.put(). Uma linha em blob_refs mapeia o caminho logico (tessera + memoria + arquivo) para o hash CAS. Leituras buscam o hash CAS via blob_refs e leem de cas.get(). Deletar uma tessera libera todas as suas referencias de blob em uma unica transacao.

FsFragmentStore com CAS (tesseras-storage/src/fragment.rs) — Mesmo padrao para fragmentos codificados com erasure coding. O checksum BLAKE3 de cada fragmento ja e computado durante a codificacao Reed-Solomon, entao e usado diretamente como chave CAS. A verificacao de fragmentos agora checa o hash CAS ao inves de recomputar do zero — se o CAS diz que os dados estao intactos, estao.

Coletor de lixo sweep (cas.rs:sweep()) — Uma passagem periodica de GC que trata tres casos limite que o caminho normal de refcount nao consegue:

Arquivos orfaos — arquivos em disco sem linha correspondente em cas_objects. Pode acontecer apos um crash durante escrita. Arquivos com menos de 1 hora sao pulados (periodo de graca para escritas em andamento); orfaos mais antigos sao deletados.
Refcounts vazados — linhas em cas_objects com refcount zero que nao foram limpas (ex: se o processo morreu entre decrementar e deletar). Essas linhas sao removidas.
Idempotente — executar sweep duas vezes produz o mesmo resultado.

O sweep e conectado ao loop de reparo existente em tesseras-replication, entao roda automaticamente a cada 24 horas junto com as verificacoes de saude dos fragmentos.

Migracao do layout antigo (tesseras-storage/src/migration.rs) — Uma estrategia de migracao copy-first que move dados do layout antigo baseado em diretorios (blobs/<tessera>/<memoria>/<arquivo> e fragments/<tessera>/<indice>.shard) para o CAS. A migracao:

Verifica a versao de armazenamento em storage_meta (versao 1 = layout antigo, versao 2 = CAS)
Percorre os diretorios antigos blobs/ e fragments/
Computa hashes BLAKE3 e insere no CAS via put() — duplicatas sao automaticamente deduplicadas
Cria entradas correspondentes em blob_refs / fragment_refs
Remove diretorios antigos somente apos todos os dados estarem seguros no CAS
Atualiza a versao de armazenamento para 2

A migracao roda na inicializacao do daemon, e idempotente (segura para re-executar) e reporta estatisticas: arquivos migrados, duplicatas encontradas, bytes economizados.

Metricas Prometheus (tesseras-storage/src/metrics.rs) — Dez novas metricas para observabilidade:

Metrica	Descricao
`cas_objects_total`	Total de objetos unicos no CAS
`cas_bytes_total`	Total de bytes armazenados
`cas_dedup_hits_total`	Numero de escritas que encontraram um objeto existente
`cas_bytes_saved_total`	Bytes economizados por deduplicacao
`cas_gc_refcount_deletions_total`	Objetos deletados quando refcount chegou a zero
`cas_gc_sweep_orphans_cleaned_total`	Arquivos orfaos removidos pelo sweep
`cas_gc_sweep_leaked_refs_cleaned_total`	Linhas de refcount vazadas limpas
`cas_gc_sweep_skipped_young_total`	Orfaos jovens pulados (periodo de graca)
`cas_gc_sweep_duration_seconds`	Tempo gasto no sweep GC

Testes baseados em propriedades — Dois testes proptest verificam invariantes do CAS sob entradas aleatorias:

refcount_matches_actual_refs — apos N operacoes aleatorias de put/release, o refcount sempre corresponde ao numero real de referencias pendentes
cas_path_is_deterministic — o mesmo hash sempre produz o mesmo caminho no sistema de arquivos

Atualizacao de testes de integracao — Todos os testes de integracao em tesseras-core, tesseras-replication, tesseras-embedded e tesseras-cli atualizados para os novos construtores com CAS. Testes de deteccao de adulteracao atualizados para funcionar com o layout de diretorio CAS.

347 testes passam em todo o workspace. Clippy limpo com -D warnings.

Decisoes de arquitetura

BLAKE3 como chave CAS: o hash de conteudo que ja computamos para verificacao de integridade serve tambem como chave de deduplicacao. Nenhuma etapa adicional de hashing — o hash computado durante create ou replicate e reutilizado como endereco CAS.
Refcount SQLite ao inves de reflinks do sistema de arquivos: consideramos usar copy-on-write no nivel do sistema de arquivos (reflinks em btrfs/XFS), mas isso amarraria o Tesseras a sistemas de arquivos especificos. Refcounting em SQLite funciona em qualquer sistema de arquivos, incluindo FAT32 em pendrives baratos e ext4 em Raspberry Pis.
Diretorios de prefixo hexadecimal de dois niveis: armazenar todos os objetos CAS em um diretorio plano desaceleraria sistemas de arquivos com milhoes de entradas. A divisao <prefixo 2 chars>/ limita qualquer diretorio individual a ~65k entradas antes de um segundo nivel ser necessario. Isso segue a abordagem usada pelo object store do Git.
Periodo de graca para arquivos orfaos: o sweep GC pula arquivos com menos de 1 hora para evitar deletar objetos sendo escritos por uma operacao concorrente. Esta e uma escolha pragmatica — troca uma pequena janela de potenciais orfaos por seguranca contra crashes sem exigir fsync ou commit de duas fases.
Migracao copy-first: a migracao copia dados para o CAS antes de remover diretorios antigos. Se o processo for interrompido, os dados antigos permanecem intactos e a migracao pode ser re-executada. Isso e mais lento que mover arquivos mas garante zero perda de dados.
Sweep no loop de reparo: ao inves de adicionar um timer separado de GC, o sweep CAS aproveita o loop de reparo existente de 24 horas. Isso mantem o daemon simples — um unico ciclo de manutencao em segundo plano cuida tanto da saude dos fragmentos quanto da limpeza de armazenamento.

O que vem a seguir

Fase 4 continuacao — auditorias de seguranca, empacotamento para OS (Alpine, Arch, Debian, OpenBSD, FreeBSD)
Fase 5: Exploracao e Cultura — navegador publico de tesseras por era/localizacao/tema/idioma, curadoria institucional, integracao genealogica (FamilySearch, Ancestry), exportacao para midia fisica (M-DISC, microfilme, papel livre de acido com QR), contexto assistido por IA

A deduplicacao de armazenamento completa a historia de eficiencia de armazenamento do Tesseras. Um no que armazena fragmentos para milhares de usuarios — comum para nos institucionais e nos completos sempre ligados — agora paga o custo de disco apenas por dados unicos. Combinado com codificacao de apagamento Reed-Solomon (que ja minimiza redundancia no nivel da rede), o sistema alcanca armazenamento eficiente tanto nas camadas local quanto distribuida.